add_rule
Create and install a new Karabiner-Elements keyboard remapping rule with immediate effect, supporting simple key remaps, modifiers, tap/hold actions, and app-specific conditions.
Instructions
Create and install a new Karabiner-Elements rule.
Writes the rule to an asset file AND installs it in karabiner.json for immediate effect. Karabiner-Elements auto-reloads on file change.
For simple remaps, use to_key_code. For tap-vs-hold, combine to_key_code (held behavior) with to_if_alone_key_code (tap behavior).
Examples:
Simple remap (caps->esc): from_key_code="caps_lock", to_key_code="escape"
With modifier (ctrl+h->backspace): from_key_code="h", from_mandatory_modifiers=["control"], to_key_code="delete_or_backspace"
Tap/hold (caps: tap=esc, hold=ctrl): from_key_code="caps_lock", to_key_code="left_control", to_if_alone_key_code="escape"
App-specific: add app_if=['^com.apple.Terminal$']
Shell command: from_key_code="f5", to_shell_command="open -a Safari"
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_if | No | Bundle ID regexes — rule only fires in these apps (e.g. ['^com\\.apple\\.Terminal$']). Use app_unless for the inverse. | |
| to_keys | No | Full output key list. Each entry: {key_code, modifiers[], pointing_button}. Use instead of to_key_code for multi-key or complex outputs. | |
| device_if | No | Device identifiers — rule only fires on these devices. Each dict may contain: vendor_id (int), product_id (int), location_id (int), is_keyboard (bool), is_pointing_device (bool). | |
| app_unless | No | Bundle ID regexes — rule fires everywhere EXCEPT these apps. | |
| asset_title | No | Asset file group title. Rules with the same title go in the same file. Default: 'MCP Rules'. | |
| description | Yes | Human-readable rule description. Must be unique across all rules. | |
| to_key_code | No | Output key code (shorthand for a single to-key). For multiple outputs or modifiers on output, use to_keys instead. | |
| to_modifiers | No | Modifiers to apply to the output key (used with to_key_code). | |
| device_unless | No | Device identifiers — rule fires on all devices EXCEPT these. Same fields as device_if. | |
| from_key_code | No | Trigger key code (e.g. 'caps_lock', 'a', 'left_command'). Mutually exclusive with from_pointing_button. | |
| profile_index | No | Profile to install the rule in. Omit for the selected profile. | |
| to_shell_command | No | Shell command to execute when the rule fires (e.g. 'open -a Terminal'). | |
| from_pointing_button | No | Trigger mouse button (e.g. 'button1'). Mutually exclusive with from_key_code. | |
| to_if_alone_key_code | No | Key to send if the trigger is tapped briefly (not held). Common for dual-purpose keys like 'caps_lock as escape when tapped, control when held'. | |
| from_optional_modifiers | No | Modifiers allowed but not required. Use ['any'] to ignore all extra modifiers (recommended for most remaps). | |
| from_mandatory_modifiers | No | Modifiers that must be held for the rule to fire (e.g. ['command', 'shift']). Use search_key_codes to find valid names. | |
| to_if_held_down_key_code | No | Key to send if the trigger is held down past the threshold. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |