Kanata provides more readable keyboard remapping configurations than Karabiner-Elements. To run it automatically on macOS startup, set it up as a LaunchDaemon.

Install Kanata via Homebrew:

1

brew install kanata

Download and install the Karabiner VirtualHIDDevice driver. Kanata needs this to interact with macOS.

Create your Kanata configuration at ~/.config/kanata/config.kbd. See the documentation for examples. Add a key combo to reload your configuration (command: lrld) to avoid manually restarting.

Create two .plist files in /Library/LaunchDaemons/ to launch Kanata at startup.

First, org.custom.karabiner.plist for the Karabiner driver:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

<?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>org.custom.karabiner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Next, create org.custom.kanata.plist to launch Kanata:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<?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>org.custom.kanata</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/kanata</string>
        <string>--cfg</string>
        <string>/Users/YOUR_USERNAME/.config/kanata/config.kbd</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Important: Replace /Users/YOUR_USERNAME/.config/kanata/config.kbd with your actual .kbd file path. To find the correct Kanata binary path, run which kanata in your terminal.

Load both daemons with these commands:

1
2

sudo launchctl load /Library/LaunchDaemons/org.custom.karabiner.plist
sudo launchctl load /Library/LaunchDaemons/org.custom.kanata.plist

Kanata should start running in the background within a few seconds. It will now launch automatically on every boot.

Stop Kanata with sudo launchctl unload /Library/LaunchDaemons/org.custom.kanata.plist. Emergency escape: press Left Control + Space + Escape at their original positions.

Credit:

  • Setup based on configuration shared by u/matklad on Reddit