Reference

• 1: Configuration file
• 2: Diagnostics and recovery
• 3: Uninstall
• 4: Privacy
• 5: FAQ

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.

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.

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

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.