Customize

• 1: Keyboard editor
• 2: App rules
• 3: Actions
• 4: Hyper mode and profile behaviour
• 5: Settings, menu bar and statistics

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.

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

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.

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.