This skill should be used when the user asks to "remap keys", "set up a hyper key", "create Karabiner rules", "configure keyboard shortcuts", "create complex modifications", "set up dual-function keys", "configure app-specific shortcuts", or any Karabiner-Elements setup and troubleshooting on macOS.
From karabiner-elementsnpx claudepluginhub grailautomation/claude-plugins --plugin karabiner-elementsThis skill uses the workspace's default tool permissions.
assets/common_rules.jsonassets/key_codes_reference.jsonreferences/conditions.mdreferences/key-codes.mdreferences/maintenance.mdreferences/parameters.mdreferences/patterns.mdreferences/software-functions.mdscripts/config_manager.pyscripts/inspect_environment.shConfigure, customize, and troubleshoot Karabiner-Elements on macOS — including key remapping, complex modifications, profiles, and device-specific rules.
CONFIG_FILE: ~/.config/karabiner/karabiner.json
COMPLEX_MODS_DIR: ~/.config/karabiner/assets/complex_modifications/
CLI_PATH: /Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli
DEVICES_FILE: ~/.local/share/karabiner/karabiner_grabber_devices.json
LOG_DIR: /var/log/karabiner/
The main karabiner.json structure:
{
"global": { "check_for_updates_on_startup": true, "show_in_menu_bar": true },
"profiles": [
{
"name": "Default",
"selected": true,
"simple_modifications": [],
"fn_function_keys": [],
"complex_modifications": { "parameters": {}, "rules": [] },
"virtual_hid_keyboard": { "keyboard_type": "ansi" },
"devices": [],
"parameters": {}
}
]
}
# Profile management
'$CLI_PATH' --list-profile-names
'$CLI_PATH' --show-current-profile-name
'$CLI_PATH' --select-profile 'Profile Name'
# Variable management
'$CLI_PATH' --set-variables '{"my_var":1, "another_var":true}'
# Configuration validation
'$CLI_PATH' --lint-complex-modifications "~/.config/karabiner/assets/complex_modifications/*.json"
# Version and help
'$CLI_PATH' --version
'$CLI_PATH' --help
Before making changes, gather context about the installation, current config, connected devices, and active profile. Use the inspection script at scripts/inspect_environment.sh to automate this.
Each complex modification rule follows this pattern:
{
"description": "Human-readable description",
"manipulators": [
{
"type": "basic",
"from": {
"key_code": "source_key",
"modifiers": { "mandatory": ["modifier1"], "optional": ["any"] }
},
"to": [{ "key_code": "target_key", "modifiers": ["modifier"] }],
"to_if_alone": [],
"to_if_held_down": [],
"to_after_key_up": [],
"to_delayed_action": {
"to_if_invoked": [],
"to_if_canceled": []
},
"conditions": [],
"parameters": {}
}
]
}
When a user requests a new mapping:
Always back up before modifying:
cp ~/.config/karabiner/karabiner.json ~/.config/karabiner/karabiner.json.backup.$(date +%Y%m%d%H%M%S)
Use the configuration manager at scripts/config_manager.py for safe JSON manipulation.
"selected": true)device_if conditions to target specific keyboards