Skip to content

Instantly share code, notes, and snippets.

@ubergoober
Created September 18, 2025 21:36
Show Gist options
  • Select an option

  • Save ubergoober/91421ca7f650a62b93cd449312eb9665 to your computer and use it in GitHub Desktop.

Select an option

Save ubergoober/91421ca7f650a62b93cd449312eb9665 to your computer and use it in GitHub Desktop.
Remap MacOS Capslock for ghostty

Native way to remap the capslock key to the key f18 for configuring the quick terminal within ghostty without using a tool like Karabiner Elements. This renders capslock useless for any other task, but I only use capslock for my quickterm. You can of course remap any other key.

Limitation: This remaps the capslock to only a single key which can't be used as a modifier key (perhaps unless you remap it to one, in which case just use the native MacOS modifier remapping setting in Preferences. This means you can't use it for keycombos. If you dedicate it like I did to just the quickterm, this shouldn't be an issue.

Configure ghostty for using f18 as the quick terminal hotkey. In the ghostty config, add, or modify the quick terminal hotkey line to:

keybind = global:f18=toggle_quick_terminal

The following won't persist after reboot (we'll fix that), so it's good to use as a test. Run this command in the terminal to map the capslock to f18:

hidutil property --set \
 '{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":0x700000039,
 "HIDKeyboardModifierMappingDst":0x70000006D}]}'

Test in ghostty (you may have to reload the config or even restart ghostty completely).

If all is working as expected, you can do the following to add it persistant after reboots. Create the following file if it doesn't exist:

~/Library/LaunchAgents/com.local.KeyRemapping.plist

Add the following to that file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.local.KeyRemapping</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/hidutil</string>
        <string>property</string>
        <string>--set</string>
        <string>{"UserKeyMapping":[
            {
              "HIDKeyboardModifierMappingSrc": 0x700000039,
              "HIDKeyboardModifierMappingDst": 0x70000006D
            }
        ]}</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

All should be good now.

References:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment