• This script is exclusively for Apple Silicon MacBooks where keyboard brightness function keys have been removed and cannot be remapped through System Settings.
• If you've already configured custom hidutil key bindings, please see the Manual Configuration section.

This script restores the keyboard brightness controls (up/down) to the function key row, just like on older Intel MacBooks.

The tool uses hidutil, Apple's key remapping utility introduced in macOS 10.12 Sierra alongside the IOHIDEventSystemClient API. For more details, see Apple's Technical Note TN2450.

You can choose from three different key positions:

• Classic (F5 & F6): Maps to the same position as older MacBooks
  • Replaces: Dictation (F5) and Focus Mode (F6)
• Mid (F4 & F5): A compromise between the other options
  • Replaces: Spotlight (F4) and Dictation (F5)
• Left (F3 & F4): Places controls next to screen brightness keys
  • Replaces: Launchpad (F3) and Spotlight (F4)

Note: Other function keys (screen brightness, media controls, volume) aren't included as mapping options since they're used more frequently. For custom configurations, see Manual Configuration.

1. Clone the repository: $ git clone https://github.com/ZoCrit/kbx.git
   • Alternatively, download and extract the ZIP file manually
2. Navigate to the project directory: $ cd kbx
3. Make the script executable: $ chmod +x kbx
4. Run the script: $ ./kbx
5. Choose your preferred keyboard brightness mapping by entering a number (1-3)
   • Press 0 to exit the script
   • Screenshots

If you prefer to set up the key remapping manually instead of using the script:

1. Create the LaunchAgents directory if it doesn't exist:

   sudo mkdir -p /Library/LaunchAgents

2. Create the configuration file:

   sudo touch /Library/LaunchAgents/com.local.KeyRemapping.plist

3. Open the file in your preferred text editor (with sudo privileges)
4. Copy and paste the plist content for your desired configuration from Plist Configurations
5. Save the file and load the configuration:

   sudo launchctl load /Library/LaunchAgents/com.local.KeyRemapping.plist

6. Apply the mapping immediately using the terminal command from Terminal Commands

1. Unload and delete the configuration file:

   sudo launchctl unload /Library/LaunchAgents/com.local.KeyRemapping.plist
   sudo rm /Library/LaunchAgents/com.local.KeyRemapping.plist

2. Clear any active key mappings:

   hidutil property --set '{"UserKeyMapping":[]}'

<?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": 0xC000000CF,
              "HIDKeyboardModifierMappingDst": 0xFF00000009
            },
            {
              "HIDKeyboardModifierMappingSrc": 0x10000009B,
              "HIDKeyboardModifierMappingDst": 0xFF00000008
            }
        ]}</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Use the Classic configuration above, but change these hex values:

• 0xC000000CF → 0xC00000221
• 0x10000009B → 0xC000000CF

Use the Classic configuration above, but change these hex values:

• 0xC000000CF → 0xFF0100000010
• 0x10000009B → 0xC00000221

Use these commands to apply the key mappings immediately (useful for testing):

hidutil property --set '{"UserKeyMapping":[
  {
    "HIDKeyboardModifierMappingSrc": 0xC000000CF,
    "HIDKeyboardModifierMappingDst": 0xFF00000009
  },
  {
    "HIDKeyboardModifierMappingSrc": 0x10000009B,
    "HIDKeyboardModifierMappingDst": 0xFF00000008
  }
]}'

hidutil property --set '{"UserKeyMapping":[
  {
    "HIDKeyboardModifierMappingSrc": 0xC00000221,
    "HIDKeyboardModifierMappingDst": 0xFF00000009
  },
  {
    "HIDKeyboardModifierMappingSrc": 0xC000000CF,
    "HIDKeyboardModifierMappingDst": 0xFF00000008
  }
]}'

hidutil property --set '{"UserKeyMapping":[
  {
    "HIDKeyboardModifierMappingSrc": 0xFF0100000010,
    "HIDKeyboardModifierMappingDst": 0xFF00000009
  },
  {
    "HIDKeyboardModifierMappingSrc": 0xC00000221,
    "HIDKeyboardModifierMappingDst": 0xFF00000008
  }
]}'

Top to bottom: Main menu, Configuration selection, Delete option