Documentation

• 1: Get started
  • 1.1: Install and first run
  • 1.2: Learn the layout
  • 1.3: Coexisting with Karabiner-Elements
• 2: Default layout
  • 2.1: Navigation and selection
  • 2.2: Mouse and scrolling
  • 2.3: Editing, symbols and clipboard
  • 2.4: Windows and apps
  • 2.5: Function and media keys
• 3: Customize
  • 3.1: Keyboard editor
  • 3.2: App rules
  • 3.3: Actions
  • 3.4: Hyper mode and profile behaviour
  • 3.5: Settings, menu bar and statistics
• 4: Reference
  • 4.1: Configuration file
  • 4.2: Diagnostics and recovery
  • 4.3: Uninstall
  • 4.4: Privacy
  • 4.5: FAQ
• 5: Karabiner Edition
  • 5.1: Install and Hyper basics
  • 5.2: Navigation, deletion, and mouse
  • 5.3: Windows and developer workflows
  • 5.4: System functions and reference
  • 5.5: Configurator
  • 5.6: Earlier versions
    • 5.6.1: Mac V2
    • 5.6.2: Mac V1
    • 5.6.3: Windows

1 - Get started

Install Capslock, finish the short onboarding, and learn the default layout in the app's own Playground. If you used the Karabiner-Elements configuration before, read the Karabiner page before you start.

1.1 - Install and first run

Requirements

• macOS 14 Sonoma or later, on Apple silicon or Intel.
• The Accessibility permission. Capslock never asks for Input Monitoring.
• Caps Lock not already remapped by another tool. If you use Karabiner-Elements, read Coexisting with Karabiner-Elements first.

Install

Open Capslock.dmg and drag Capslock into Applications. Then open it from Applications or Spotlight.

Capslock runs as an ordinary app with a window, a Dock icon, and a menu-bar icon. Closing the window keeps it running in the menu bar.

Onboarding

On the first launch Capslock takes over nothing. The keyboard keeps working as before until you finish onboarding.

1. Welcome to Capslock. Click Continue.
2. Choose a Hyper mode. Classic, the default, also holds ⌃⌥⇧⌘ while Caps Lock is down, so Hyper shortcuts in apps such as Alfred and Raycast keep working. Native keeps Caps Lock chords inside Capslock. You can change this later; see Hyper mode.
3. Before you start. The Keyboard access card shows whether Capslock may read Caps chords and send keystrokes. Click Open System Settings. macOS opens Privacy & Security › Accessibility; turn on Capslock and confirm with your password. Back in Capslock, click Start Capslock. The Conflicts card below lists anything else that uses Caps Lock. To finish without starting, click Skip for Now.
4. Explore your keyboard. Click Open Keyboard. The Keyboard page shows the layout, and you can browse and edit it even while Capslock is paused.

Check that it works

Home shows Running and "Caps Lock is your Hyper key." Its status card should read:

Then try the four gestures from First steps on Home:

• Tap Caps Lock: Escape.
• Hold Caps Lock and press H, J, K or L: the cursor moves left, down, up or right, in any app.
• Hold Caps Lock and press Space: the input source changes, if you have more than one and the ⌃Space shortcut is on.
• Hold Caps Lock and wait: the whole current plane appears on screen.

If a row is not healthy, its link opens Diagnostics, where every check has numbered steps and buttons that fix it.

Everyday controls

• Pause on Home, in Settings, or in the menu-bar menu gives Caps Lock back to macOS until you click Resume.
• Open at login is in Settings › General and is off by default.
• Hide Dock icon in the same section leaves only the menu-bar icon.
• Quitting Capslock restores Caps Lock before the app exits.

1.2 - Learn the layout

Nobody memorizes 357 bindings up front. Capslock teaches the layout in three ways: it shows the current plane when you pause, it can show each action as it runs, and the Playground has short lessons that follow your own mappings.

Hold-to-Reveal

Hold Caps Lock without pressing another key. After a short delay the current plane appears on screen as a full keyboard with every action written on its key. Press ⌘, ⌥, ⌃ or ⇧ to switch planes while it is open; release Caps Lock to close it.

It is on by default. In Settings › Hyper you can turn it off, change the delay (550 ms by default, 250 to 1500 ms), and choose whether it hides when an action runs or only when you release Caps Lock.

Show actions on screen

Settings › Hyper › Show actions on screen displays a small caption at the bottom of the screen each time a chord runs: the keys you pressed and the action they produced. It is off by default; the caption stays for 1.35 seconds unless you change the duration.

Playground

The Playground page has three parts, chosen under Lesson:

• Basics practises four gestures: tap Caps Lock for Escape, hold it to reveal the plane, ⇪ Esc to toggle Caps Lock, and ⇪ Space to switch input source.
• Navigate practises moving with ⇪ H, ⇪ J, ⇪ K and ⇪ L.
• Free Play shows the last key you pressed: the plane, the action, the app in front, and whether the action ran, was previewed, was blocked, or the key passed through.

Lessons read your current mappings. If you changed or disabled a key a lesson uses, the lesson says so instead of asking for a key that no longer does what it describes.

Live and Safe Practice

The Mode switch chooses between Live, where chords really run, and Safe Practice. In Safe Practice, actions with side effects are previewed instead of run: opening apps, Shell commands, sleep, clipboard slots, and toggling Caps Lock. Keystrokes and mouse actions still run, so you can see the cursor move.

Safe Practice turns itself off when you leave the Playground, hide the window, or switch to another app.

Free Play keeps only the most recent key, only while the Playground is in front, and clears it when you leave. Nothing you type is recorded.

The Keyboard page

The Keyboard page draws your keyboard with each key's action on it. Choose a plane from the menu or with the ⌘ ⌥ ⌃ ⇧ toggles. While you hold Caps Lock, the drawing follows the plane you are actually on and shows a Live badge. Key legends follow your active keyboard layout, so Dvorak or AZERTY users see their own letters. Click a key to see or change it; see Keyboard editor.

1.3 - Coexisting with Karabiner-Elements

Capslock needs Caps Lock and the F18 key to itself. It never edits, disables, or uninstalls Karabiner-Elements or any other tool. When something else already uses those keys, Capslock refuses to start and tells you what to change.

What counts as a conflict

• A system key remap of Caps Lock. If another tool has remapped Caps Lock, Diagnostics shows "Caps Lock is used by another tool".
• Another use of F18. If anything remaps a key to or from F18, Diagnostics shows "F18 is already in use".
• A Karabiner-Elements rule. When Karabiner-Elements is running, Capslock reads the selected profile and looks for rules that start from Caps Lock or F18, or that produce F18. It reports only how many it found, never their names or contents.

Karabiner-Elements can keep running for everything else. Only rules on Caps Lock and F18 conflict.

Resolving a Karabiner conflict

1. Open Karabiner-Elements › Complex Modifications.
2. Turn off the rule that starts from Caps Lock (such as "CapsLock to Hyper"), or switch to a profile without it.
3. Return to Capslock and click Try Again on Home or in Diagnostics.

Diagnostics has an Open Karabiner-Elements button for step 1. Capslock checks again every time you switch back to it, so a conflict that appears later stops Capslock and gives Caps Lock back rather than leaving two tools fighting over it.

Moving from the Karabiner configuration

The native app ships the same Capslock Classic layout, so you do not need to bring anything across to keep the bindings you know. A few things work differently:

• Tapping Caps Lock sends Escape. ⇪ Space sends ⌃Space for switching input source.
• You choose a Hyper mode. Classic, the default, still holds the right-side ⌃⌥⇧⌘ for apps that listen for Hyper.
• Clipboard slots are stored encrypted inside Capslock. Files such as ~/.clip6 from the Karabiner setup are not read.
• Apps are opened by bundle ID, not through open -a in a shell.
• Changes you made to your own Karabiner JSON are not imported. Recreate them in the keyboard editor.

When you are ready, turn off the Capslock rules in Karabiner-Elements as described above, then start Capslock. The Karabiner configuration itself stays documented in the Karabiner Edition if you want to go back.

2 - Default layout

A fresh install starts with the complete Capslock Classic V3 layout: 357 bindings, one for tapping Caps Lock and 356 for holding it with another key. Nothing has to be configured before it works. These pages list every binding. In the app, the Keyboard page shows the same layout, one plane at a time, and Hold-to-Reveal shows it while you type.

How to read the tables

⇪ means "hold Caps Lock". ⇪ H is: hold Caps Lock, press H. ⇪ ⌘ H is: hold Caps Lock and Command, press H. Modifier glyphs follow the macOS order: ⌃ Control, ⌥ Option, ⇧ Shift, ⌘ Command.

In the default Classic Hyper mode only the left Command, Option, Control and Shift choose a plane. The right-side ones are what Capslock itself holds down for other apps; see Hyper mode.

The Caps Lock key

A tap counts only if you release Caps Lock within one second and press no other key, mouse button, or scroll wheel in between. Modifiers you already hold travel with the Escape: hold Shift and tap Caps Lock to send ⇧Esc.

The sixteen planes

The modifiers you hold with Caps Lock choose one of sixteen planes. Each modifier is a bit (Command 1, Option 2, Control 4, Shift 8), and the plane number is their sum. Matching is exact: a chord with an extra modifier never falls back to a plane with fewer.

The seven "Custom" planes are free for your own bindings. Only the five keypad mouse buttons are bound there, so that a click keeps working whatever modifiers you hold.

Apps the layout opens

Twenty-three bindings open an app, among them Safari, iTerm, Visual Studio Code, Alfred, Codex and Claude. If an app is not installed, its key does nothing. The full list is in Windows and apps.

What the layout does not contain

• No Shell commands. App launches, sleep, and clipboard slots are built-in actions, so nothing in the default layout runs a script.
• No double-tap bindings and no per-app rules. Both are available for your own mappings.
• ⇪ A and the number keys 1 to 5 have no binding on the base plane.

2.1 - Navigation and selection

The eight keys under your right hand, H J K L and U I O P, carry most of the layout. On the base plane they move the cursor; other planes turn them into selection, tab and app switching, Spaces, the mouse, and scrolling. The mouse and scroll planes are on Mouse and scrolling.

Move and select

⇪ I and ⇪ O send the Home and End keys, not ⌘← and ⌘→. Some Mac text views scroll on Home and End instead of moving the cursor; where you want the start or end of the line, rebind them in the editor.

Arrow keys keep working as usual. A single key such as ← repeats while you hold the chord, exactly like the real arrow key.

Tabs, apps, windows and Spaces

Spaces, App Exposé, and screen zoom follow the shortcuts set in macOS System Settings. If you changed or turned off one of those shortcuts, the chord sends the same keys but macOS does nothing with them.

More switching keys sit on the left hand: see Windows and apps.

2.2 - Mouse and scrolling

Capslock can drive the pointer from three places: the letter keys under your right hand, the arrow keys, and the numeric keypad. Movement and scrolling run smoothly for as long as you hold the chord. Mouse buttons are held while you hold the chord, so holding a click chord and moving drags.

On the letter keys

On the two scroll planes, U I O P scroll in the opposite direction to H J K L. Fast movement is twice the normal speed; fast scrolling is twice the normal scroll.

On the arrow keys

The reversed direction on ⇪ ⇧ ⌘ is carried over unchanged from the Karabiner-Elements layout. Rebind the four arrows on that plane if you prefer it to match.

Clicks on Return

On the numeric keypad

With a numeric keypad, keys 1 to 9 move in eight directions, laid out like the keypad itself: 7 up-left, 8 up, 9 up-right, 4 left, 6 right, 1 down-left, 2 down, 3 down-right. Key 5 does nothing.

The keypad buttons work on all sixteen planes. Any modifier you hold is applied to the click, so ⇪ ⌘ 0 on the keypad is a ⌘-click.

On the base plane the remaining keypad keys scroll slowly: / and = vertically, * and Clear horizontally.

2.3 - Editing, symbols and clipboard

Delete

N M , . sit below the navigation keys and delete in both directions.

⌥⇧↑ and ⌥⇧↓ move a line in editors that use those shortcuts, such as Visual Studio Code. Elsewhere they extend a selection.

Symbols

Symbols that need Shift move onto unshifted chords. These bindings type the characters of a US keyboard layout.

⇪ ; then ⇪ ' types :=; ⇪ ⌘ ; then ⇪ ' types !=.

Five more clipboards

The top-row digits 6 to 0 are five clipboard slots.

A slot keeps everything that was copied, not only text, so images and rich text survive. Pasting from a slot replaces what was on the system clipboard. Slots are encrypted on disk with a key kept in your Keychain, and their contents are never written to the log.

Terminal and editor keys

⇪ X sends ⌃R, not ⌃X, and ⇪ C opens an app rather than sending ⌃C. F5 and ⌃F5 start debugging and run without debugging in Visual Studio Code.

2.4 - Windows and apps

Window control

Tab, Q, W, A and S sit under the left hand, so you can switch and close while the right hand stays on the mouse or the navigation keys.

⇪ A on its own has no binding. Sleep the display and Sleep the Mac are built-in actions that run immediately; in the Playground's Safe Practice mode they are only previewed.

Open apps

E, R, T, Y, F and G open apps, three per key. An app that is not installed is skipped: the key does nothing until you install it.

⇪ ⌃ P, ⇪ ⌃ A and ⇪ F4 open Apps (Launchpad on older macOS).

Apps are matched by bundle ID, not by name or path, so they open wherever they are installed. To open a different app, pick the key in the keyboard editor and choose Open app.

2.5 - Function and media keys

The function row

These chords need the key to arrive as a real F-key. If the top row of your keyboard controls brightness and volume by default, hold fn as well, or turn on "Use F1, F2, etc. keys as standard function keys" in System Settings. ⌃1 to ⌃3 switch desktops only when those shortcuts are enabled in System Settings.

Fine adjustment

The editing cluster above the arrow keys sends ⇧⌥ with a media key, which macOS treats as a quarter step.

3 - Customize

Everything on these pages is done in the app. You never need to edit a file by hand, although the configuration file is plain YAML if you want to.

3.1 - Keyboard editor

The Keyboard page is the editor. It draws your keyboard for the selected plane with each mapped action on its key. Keys your keyboard lacks, such as F16 or a numeric keypad on a laptop, appear under Keys not on this keyboard, and tap and double-tap mappings appear under Other triggers. Switch to List in the toolbar for a list grouped by trigger type.

Change one key

Click a key. A popover shows its chord, the plane, and the current Action:

• Change picks another built-in action or one of your custom actions.
• Edit… opens the full mapping editor, described below.
• Show YAML shows that mapping exactly as it is stored.
• Restore Classic puts back the Capslock Classic action. It appears only when the key differs from the Classic layout.

Three buttons stop a key from doing its mapped action. They differ in what the key does afterwards:

A key with no mapping shows "Not mapped on this plane", what it does now, and Assign Action.

Write a mapping

Click + in the toolbar, or Edit… on a key, to open the mapping editor.

Trigger. Choose one of:

• Caps + Key: press the key to capture it, then pick the plane with the ⌘ ⌥ ⌃ ⇧ toggles.
• Tap Caps: what a tap of Caps Lock does (Escape by default).
• Double-tap Caps: two taps within the double-tap window. A single tap then waits for that window before it runs.
• Double-tap Modifier: two taps of left or right ⌘, ⌃, ⌥, ⇧, or fn (fn is experimental).

Change Trigger moves an existing mapping to another key, plane, or trigger; its action and app rules move with it.

Default action. The action that runs in every app, unless an app rule below matches. Pick a built-in action, one of your custom actions, New Action…, or define one inline.

App rules. Optional. Each rule names one or more apps and an action for them. See App rules.

Each key and plane can hold one mapping; the editor refuses a duplicate.

How changes are applied

Every save is checked first, then the whole configuration is written to disk in one step, and only then does the running keyboard switch over. A change either applies completely or not at all.

Undo and Redo in the toolbar, or ⌘Z and ⇧⌘Z, reverse the last change to your mappings. One step is kept, and the history is cleared when Capslock relaunches.

If you edit the configuration file in another app, Capslock reloads it the next time you switch to Capslock. A save that would overwrite such an outside change is refused, so you can make your change again on top of it.

Import, export, and the Classic layout

The More menu in the toolbar has three commands:

• Export writes your whole configuration, including custom actions and profile behaviour, to one YAML file (capslock-config.yml by default).
• Import reads such a file and replaces all of your current mappings. Custom actions are merged. Your current file is backed up first. Shell commands and sleep actions in the imported file are switched off until you review and trust them again.
• Install Capslock Classic V3 reinstalls the built-in layout. It first shows a verified preview, including which of the apps it opens are not installed, then asks before replacing your mappings. Your custom actions, app settings, and Hyper mode stay as they are, and a backup is saved first.

3.2 - App rules

An app rule makes a key do something different while a particular app is in front, without changing what it does everywhere else.

How rules are matched

Each mapping has a Default action and, optionally, a list of App rules. When you press the chord, Capslock checks the rules from top to bottom against the app in front. The first rule that names that app wins. If none does, the default action runs.

Apps are identified by their exact bundle ID, such as com.apple.Safari. A rule keeps working if the app is moved or renamed, and it never matches a different app with a similar name.

Add a rule

From a key:

1. Click the key on the Keyboard page, then Edit….
2. Under App rules, click Add App Rule.
3. Under Applies in, click Add App and choose one or more apps.
4. Choose the action to run in those apps, then save.

From the Apps page, click Add Rule…, choose an app, and the mapping editor opens with that app already filled in. To pick an app that is not installed yet, type its bundle ID instead of browsing.

Use the arrows next to a rule to change its order. Every rule must name at least one app.

The Apps page

The Apps page lists every app that has rules, marks the ones that are not installed, and shows each rule. From an app's menu you can add another rule for it or Remove All Rules. Removing all rules for an app is a single change: it is backed up first and can be undone.

In the configuration file

A rule is a bindings entry on the mapping. This one keeps ⇪ N deleting the previous word with ⌥⌫ everywhere, but sends ⌃W in Terminal and iTerm, where shells expect it:

- trigger:
    kind: hyper_plus_key
    key: 78            # N
    plane: 0           # Base
  action:
    kind: key_combo
    target_key: 8      # Backspace
    with_alt: true
  bindings:
  - when:
    - type: frontmost_app
      include:
      - com.apple.Terminal
      - com.googlecode.iterm2
    action:
      kind: key_combo
      target_key: 87   # W
      with_ctrl: true

Rules the editor cannot display are shown as "Advanced rule (edit in YAML)" and kept unchanged. See Configuration file.

3.3 - Actions

A mapping runs an action. Actions are either built in or yours. The Actions page lists both; built-ins cannot be edited, but any of them can be mapped.

Built-in actions

The IDs are permanent: a mapping that refers to one keeps working across versions.

Custom actions

Click New Action… on the Actions page, or define an action inline in the mapping editor. The types are:

The mouse, scrolling, sleep, clipboard-slot, and media actions used by the Classic layout appear under Mouse & system. You can map them to other keys, but not create new ones.

An action that a mapping uses cannot be deleted; the Actions page names the mappings to remove first.

Shell commands and trust

Saving a Shell command asks Trust this action? A trusted command runs with your user privileges. It can change files and use the network, and neither Pause nor Undo can reverse what it has done. Click Trust & Save to keep it. The same question appears for the Sleep Mac and Sleep Display actions.

A command is never trusted by accident:

• Editing the command text removes its trust until you approve it again.
• Every command and sleep action in an imported configuration arrives switched off, shown as "Off · needs review". Open it in the editor and save it to approve it.
• A command that is not trusted does not run, whatever the configuration file says.

Commands run in the background with their output discarded; Capslock does not log what they print.

Switching input sources

The default layout's ⇪ Space sends ⌃Space, so macOS uses whatever shortcut you set for "Select the previous input source". To jump straight to one input source instead, map a key to Switch Input Source and pick it.

Some Chinese, Japanese and Korean input sources do not take effect reliably when switched directly. Settings › Input sources offers two workarounds for Caps + key mappings that switch input source:

• Simulate shortcut presses "Select the previous input source". Reliable before macOS 26; it needs that shortcut turned on in System Settings.
• Switch focus briefly moves focus so the new input source takes hold. Better on macOS 26; it does not work in floating windows.

3.4 - Hyper mode and profile behaviour

Hyper mode

Settings › Hyper › Hyper mode has two choices. You also pick one during onboarding.

Pick Classic if you have shortcuts in other apps that rely on Hyper (⌃⌥⇧⌘), or if you are coming from the Karabiner-Elements configuration. Pick Native if nothing else listens for Hyper and you want either side's modifiers to choose a plane.

In Classic mode Capslock itself holds the right-side modifiers, which is why only the left side can choose a plane.

Unmapped chords

Settings › Profile behavior › Unmapped Caps chords decides what a chord with no mapping does, for example ⇪ A on the base plane:

A key mapped to Use Normal Key always types itself, whichever choice is set here. A key whose mapping you removed follows this setting. See Change one key.

Modifier sides

Settings › Profile behavior › Modifier sides chooses which ⌘ ⌥ ⌃ ⇧ select a plane:

• Automatic (default): left only in Classic mode, either side in Native.
• Left only.
• Either side (Native): only available in Native mode.

Both profile settings are saved inside your configuration, so they travel with an export, an import, a backup, and Undo.

Double-tap speed

Settings › Hyper › Double-tap speed is the longest gap between two taps that still counts as a double tap: 200 ms by default, from 100 to 500 ms. It applies to Double-tap Caps and Double-tap Modifier mappings.

Right-side modifiers as extra keys

Settings › Advanced › Key remaps turns a spare right-side ⌘, ⌥, ⌃ or ⇧ into F13, F14, F15, F16, F17 or F19, which you can then use as a shortcut in any app. The remapped key stops working as a modifier; its left-side twin is unaffected. F18 is reserved for Caps Lock.

3.5 - Settings, menu bar and statistics

Settings

Settings are stored in app_config.yml; see Configuration file.

The Status, Permissions and Recovery sections repeat the controls from Home and Diagnostics: Pause and Resume, the permission rows, Release All, Restore Caps Lock, and Show Config Folder.

Reset Settings… at the bottom puts every setting back to its default. Your mappings, actions and app rules stay as they are.

Menu bar

The menu-bar icon is always present: a filled ⇪ while Capslock is running, an outline while it is paused, and a warning triangle when something needs attention. Its menu contains:

• the current status;
• Pause or Resume;
• Check for Updates, in release builds;
• Capslock Website;
• Open Capslock;
• Quit Capslock (⌘Q).

Closing the main window, or pressing ⌘W, hides it; Capslock keeps running.

Statistics

The Statistics page shows how often you use each trigger, for today, the last 7 days, the last 30 days, or all time, with a Most used ranking.

• Each physical press counts once. A key held down and repeating still counts once.
• Counts belong to the trigger, so rebinding a key keeps its history.
• Daily counts are kept for 30 days; older days are folded into all-time totals.
• Only counts are stored, on this Mac. What you type is never recorded.

Reset Statistics clears every count and cannot be undone. Settings › Advanced › Show counts on mappings shows or hides the counts next to mappings.

4 - Reference

4.1 - Configuration file

You never have to edit these files: everything here can be changed in the app. They are plain YAML so that you can read them, keep them in version control, or move them to another Mac with Export and Import.

Where files are kept

Settings › Recovery › Show Config Folder opens it in Finder. Your language choice is kept in the app's preferences, and the clipboard key in your Keychain.

action_mappings.yml

The file has three parts: a capslock_profile block that Capslock maintains, your custom actions, and the mappings. Built-in actions are never written to the file.

capslock_profile:
  id: classic-v3
  version: 3.1.0
  runtime_policy:            # written only after you change profile behaviour
    unmapped_keys: passthrough
    modifier_sides: left
actions:
- id: 4C1F0A52-6E2B-4D0B-9C1E-2B7D3F8E9A10
  name: Open Calculator
  action:
    kind: open_app
    bundle_id: com.apple.calculator
    app_name: Calculator
mappings:
- trigger:
    kind: single_tap_hyper
  action_id: builtin.escape
- trigger:
    kind: hyper_plus_key
    key: 72                  # H
    plane: 0
  action_id: builtin.move_left
- trigger:
    kind: hyper_plus_key
    key: 67                  # C
    plane: 8                 # Shift
  action_id: 4C1F0A52-6E2B-4D0B-9C1E-2B7D3F8E9A10

Mappings

Actions

A command action loaded from a file you edited or imported is not trusted until you approve it in the app, even if the file says trusted: true.

app_config.yml

schema_version: 1
hyper_output_mode: classic_compatibility   # or native_clean
hold_to_reveal_enabled: true
hold_to_reveal_threshold_ms: 550
hold_reveal_dismiss_mode: action_start     # or caps_release
double_tap_window_ms: 200
show_hud: false
hud_duration_ms: 1350
theme_mode: system                         # light, dark
cjkv_fix_strategy: none                    # shortcut_simulation, switching_focus
show_window_on_launch: true
hide_dock_icon: false
stats_show_inline: true
key_remaps: []                             # e.g. {source: right_option, destination: f19}

Backups

Before a change that replaces a lot at once, such as an import, reinstalling the Classic layout, removing an app's rules, or changing profile behaviour, Capslock saves a copy of action_mappings.yml in backups/. The newest 20 are kept.

Safety rules for the files

• Unknown fields are kept. Keys, fields and whole entries that this version does not understand are written back unchanged, so a configuration from a newer version survives being opened by an older one.
• A broken file is never overwritten. If action_mappings.yml cannot be read, Capslock backs it up, shows the configuration as read-only, and does not start until you repair it or import a good one. Diagnostics reports "Configuration needs repair".
• Outside edits are detected. Changes made in another editor are reloaded when you switch back to Capslock, and a save never overwrites them.
• Older formats load. A bare list of mappings from earlier versions is read as mappings with inline actions; editing a mapping converts it to the current form.

4.2 - Diagnostics and recovery

The Diagnostics page runs a set of checks and explains, in numbered steps, how to fix any that fail. Most fixes are a button on the same row. Refresh runs the checks again.

The checks

Reset & Ask Again clears Capslock's Accessibility and keystroke-sending entries and asks again. Use it when System Settings shows Capslock as allowed but the check still fails, which can happen after replacing the app with a different build.

Getting Caps Lock back

Capslock only removes what it added. Other tools' key remaps are left alone.

If Capslock stops unexpectedly

A small helper inside the app watches Capslock while it owns Caps Lock. If Capslock crashes or is force-quit, the helper releases any keys it was holding and puts the key mapping back. On the next launch Capslock checks again before it starts, and Diagnostics notes that the last session did not quit cleanly.

Capslock also steps back on its own when it has to. When macOS stops it from reading the keyboard, when another app changes the system key mapping, or when a Karabiner rule appears, it stops and gives Caps Lock back rather than fighting over the key. After sleep it retries a few times before it reports an error. A newly connected keyboard gets the mapping too.

Restore from Terminal

If Caps Lock still behaves strangely, quit Capslock and run:

/Applications/Capslock.app/Contents/MacOS/Capslock --restore-original-caps-lock

It restores the mapping from before the last session and changes nothing it cannot verify. It refuses to run while Capslock is still running. Diagnostics shows the same command for the path where your copy is installed, with a Copy button.

Export a diagnostic report

Export… saves Capslock-Diagnostics.zip with the check results and a redacted copy of the recent log. It never includes what you type, your clipboard, Shell commands or their output, or your configuration. Attach it when you report a problem.

4.3 - Uninstall

Capslock has no installer and leaves nothing outside your user account except the Accessibility entry.

1. Quit Capslock from the menu-bar icon or with ⌘Q, so it can give Caps Lock back. If it was force-quit and Caps Lock still does not work as usual, run the restore command before you delete the app.
2. If you turned on Open at login, turn it off in Settings › General.
3. Move /Applications/Capslock.app to the Trash.
4. To remove your data as well, delete these:
   • ~/Library/Application Support/com.vonng.capslock
   • ~/Library/Preferences/com.vonng.capslock.plist
   • ~/Library/Caches/com.vonng.capslock
5. In System Settings › Privacy & Security › Accessibility, select Capslock and click −.
6. If you used clipboard slots, delete the Keychain item named com.vonng.capslock.clipboard-slots in Keychain Access.

A Mac restart also clears the Caps Lock mapping, which macOS does not keep across restarts.

4.4 - Privacy

Capslock processes keyboard and pointer events on your Mac to apply the mappings you chose. It contains no behaviour analytics or advertising SDK. It sends no mapping, key, clipboard, Shell, app-history, or usage telemetry.

What is stored locally

Everything Capslock keeps lives in your user account, under ~/Library/Application Support/com.vonng.capslock/:

• your configuration;
• clipboard slots, encrypted with a random key that is kept in your Keychain;
• a private diagnostic log, readable only by your user;
• recovery records used to give the Caps Lock mapping back after a crash;
• per-day action counters for the Statistics page.

A diagnostics export leaves out produced text, clipboard contents, Shell commands and output, secrets, raw key history, and full app history.

The Playground

Free Play keeps only the latest physical-key observation, and only while the Playground is visible and in front. It is cleared when you leave the page or the window loses focus, and it is never uploaded.

Network access

Capslock makes no network request unless you open a link yourself, or a release build checks its HTTPS update feed for a new version. Development builds have no update feed and never check.

Shell commands that you explicitly trust run with your user privileges. They can read files or use the network on their own, and Capslock does not sandbox them. Pause, Release All, and configuration Undo do not stop a process that has already started or reverse what it did. Commands in an imported configuration must be reviewed and trusted again before they run.

Permissions

Capslock asks for the macOS Accessibility permission, which its active keyboard event tap requires. It does not need Input Monitoring. Starting at login is optional and uses Apple's SMAppService.

Removing your data

Deleting the app stops it. You can also delete ~/Library/Application Support/com.vonng.capslock, its preferences and caches, and remove Capslock from the Accessibility list in System Settings. See Uninstall.

Contact

Questions about privacy: rh@vonng.com

4.5 - FAQ

Do I need Karabiner-Elements?

No. Capslock is a standalone app and builds the whole layout in. If you also run Karabiner-Elements for other keys, that is fine as long as no Karabiner rule uses Caps Lock or F18. See Coexisting with Karabiner-Elements.

Why does it need Accessibility?

To change key events, not just observe them, macOS requires an active event tap, and that requires Accessibility. Capslock does not ask for Input Monitoring, does not install a kernel extension or driver, and runs no privileged helper.

Does Capslock record what I type?

No. Keys are handled in memory and never stored or sent anywhere. The log leaves out typed text, clipboard contents and Shell output, and the Statistics page keeps only counts. See Privacy.

What if Capslock crashes while I am typing?

A helper inside the app gives Caps Lock back and releases any held keys. You can also quit Capslock and run the restore command. A restart clears the mapping too.

Can I still use Caps Lock to type capitals?

Yes. ⇪ Esc turns real Caps Lock on and off. While it is on, Capslock chords type their ordinary keys until you press ⇪ Esc again.

My keyboard has no numeric keypad.

The keypad mouse keys are optional. ⇪ with the arrow keys, ⇪ ⌥ with H J K L, and ⇪ Return move the pointer and click. See Mouse and scrolling.

Does it work with Dvorak, AZERTY or other layouts?

Chords are matched by physical key, and the Keyboard page draws your active layout's legends. The symbol bindings, such as ⇪ [ for (, type the characters of a US layout.

Why do F1 to F12 chords do nothing on my laptop?

If the top row controls brightness and volume by default, the key does not arrive as an F-key. Hold fn as well, or turn on standard function keys in System Settings › Keyboard.

A password field is open and nothing works.

macOS hides keys from every app while secure input is on, for example in a password field or with Terminal's Secure Keyboard Entry. Capslock never turns it off. Diagnostics shows when it is on.

Does Capslock run on Windows or Linux?

No. Capslock is a macOS app. The layout began on Windows as an AutoHotkey script, which is kept in the archive together with the older Karabiner versions.

5 - Karabiner Edition

Before Capslock was a native app, it was a configuration for Karabiner-Elements, and it still is. Capslock Enhancement V3 is a set of Karabiner rules that turns Caps Lock into Escape on a tap and a Hyper key on a hold, with the same sixteen control planes and the same layout that the native app ships as Capslock Classic. It is free and open source under the Apache 2.0 licence, with its source at github.com/Vonng/Capslock.

Which one should I use?

Use only one of them for Caps Lock at a time. The Capslock app refuses to start while a Karabiner rule uses Caps Lock; turn the rules off in Karabiner-Elements first, as described in Coexisting with Karabiner-Elements.

Start in three steps

1. Install Karabiner-Elements and grant the permissions it asks for.
2. Import the rules with the button on Install.
3. In Karabiner-Elements › Complex Modifications, enable every Capslock rule.

Tap Caps Lock: Escape. Hold it and press H J K L: the cursor moves.

Versions

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

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

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

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

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

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

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

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