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
| Check | Healthy | If it fails |
|---|---|---|
| Caps Lock mapping | Caps Lock is ready | Not set up, used by another tool, or unreadable. Try Again, or Restore Caps Lock. |
| F18 | F18 is free | Another tool uses F18. Remove that remap, then Try Again. |
| Karabiner-Elements | Not detected, or no conflicts | A rule uses Caps Lock or F18; see Karabiner. |
| Crash recovery | Nothing to recover | The last session did not quit cleanly and was tidied up at launch, or another copy of Capslock is running. |
| Accessibility | Granted | Open Accessibility Settings, Check Again, or Reset & Ask Again. |
| Keystroke sending | Allowed | Comes with Accessibility. Request Access, Check Again, or Reset & Ask Again. |
| Keyboard reading | Reading the keyboard | macOS stopped the event tap. Try Again, or Release All. |
| Secure input | Off | A password field or Terminal's Secure Keyboard Entry hides keys from every app. Capslock never turns it off; close the field or the option. |
| Caps Lock press | Received | Press Caps Lock once, then Refresh. |
| Configuration | Valid | The file cannot be read. Show Config Folder and repair or replace it. |
| Signature | Valid | A development build. |
| Updates | Enabled | This build does not update itself; download new versions from the website. |
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
| Control | What it does |
|---|---|
| Pause | Releases everything Capslock is holding, gives Caps Lock back to macOS, and reports "Paused. Caps Lock works as usual." once the system mapping has been checked. |
| Release All | Releases every key, modifier and mouse button Capslock is holding, without pausing. Use it if a key feels stuck. |
| Restore Caps Lock | Pauses and restores the key mapping that was in place before Capslock started, then reports whether it was verified. |
| Quit Capslock | Does the same as Pause before the app exits. |
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:
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.
hidutil property --set '{"UserKeyMapping":[]}' removes every tool's key
remaps, not only Capslock's.
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.