A human-readable configuration generator for Karabiner-Elements #1777
Description
Hi users,
I’m currently working on simplifying the configuration generation process. As a new user, I’m eager to learn about the rules and features that user's frequently uses. Could you please share some insights and configs?
https://github.com/nrjdalal/karabiner-human-config
Karabiner-Human-Config
The easiest way to write Karabiner-Elements configuration files, ever!
Find it on the official website of Karabiner-Elements at external JSON generators.
Creating configuration files for Karabiner-Elements can be challenging. With Karabiner-Human-Config (KHC), you can effortlessly generate your own configuration files using human-readable/understandable syntax.
Usage
Just create a new konfig.json file:
- Don't hold back on the comments.
- Use custom aliases like
capshypercmdctrletc. - Specify
taetc as manipulator key's aliases. - Prefix flags and delays like
100easily, if needed. - Use
$for shell command. - Just use the app's name like
Visual Studio Code.
{
// direct
"caps": { "t": "hyper", "a": "100 caps" },
"hyper spacebar": "cmd spacebar",
// group
"fn": {
"_self": { "t": "fn", "a": "cmd tab" },
"spacebar": "cmd spacebar",
"v": "$ open -a 'Visual Studio Code'"
},
// application group
"Visual Studio Code": {
"fn tilde": "ctrl tilde"
}
}And run the following command:
npx karabiner-human-configAnd voila! From 10-15 lines to 170+ lines of configuration in just a few seconds.
Generated: karabiner.json
{
"global": {
"show_in_menu_bar": false
},
"profiles": [
{
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"type": "basic",
"description": "caps",
"from": {
"key_code": "caps_lock"
},
"to": [
{
"key_code": "left_shift",
"modifiers": [
"left_command",
"left_control",
"left_option"
]
}
],
"to_if_alone": [
{
"key_code": "caps_lock",
"hold_down_milliseconds": 100
}
]
}
]
},
{
"manipulators": [
{
"type": "basic",
"description": "hyper spacebar",
"from": {
"key_code": "spacebar",
"modifiers": {
"mandatory": [
"left_command",
"left_control",
"left_option",
"left_shift"
]
}
},
"to": [
{
"key_code": "spacebar",
"modifiers": [
"left_command"
]
}
]
}
]
},
{
"manipulators": [
{
"type": "basic",
"description": "fn",
"from": {
"key_code": "fn"
},
"to": [
{
"key_code": "fn"
}
],
"to_if_alone": [
{
"key_code": "tab",
"modifiers": [
"left_command"
]
}
]
}
]
},
{
"manipulators": [
{
"type": "basic",
"description": "fn spacebar",
"from": {
"key_code": "spacebar",
"modifiers": {
"mandatory": [
"fn"
]
}
},
"to": [
{
"key_code": "spacebar",
"modifiers": [
"left_command"
]
}
]
}
]
},
{
"manipulators": [
{
"type": "basic",
"description": "fn v",
"from": {
"key_code": "v",
"modifiers": {
"mandatory": [
"fn"
]
}
},
"to": [
{
"shell_command": "open -a 'Visual Studio Code'"
}
]
}
]
},
{
"manipulators": [
{
"type": "basic",
"description": "visual studio code fn tilde",
"from": {
"key_code": "grave_accent_and_tilde",
"modifiers": {
"mandatory": [
"fn"
]
}
},
"to": [
{
"key_code": "grave_accent_and_tilde",
"modifiers": [
"left_control"
]
}
],
"conditions": [
{
"type": "frontmost_application_if",
"bundle_identifiers": [
"^com\\.microsoft\\.VSCode$"
]
}
]
}
]
}
]
},
"name": "nrjdalal",
"selected": true,
"virtual_hid_keyboard": {
"keyboard_type_v2": "ansi"
}
}
]
}
The generated configuration will be saved in karabiner.json in the same directory.
Bonus: If you wish to checkout my personal configuration, you can find it here.
And what it generates here.
Table of Contents
- CLI Usage
- Types of Addressing
- Advanced Usage for From Events
- Advanced Usage for To Events
- Alias
- Future Considerations
CLI Usage
Version:
[email protected]
Usage:
$ karabiner-human-config [options]
Options:
-i, --input Input file path (default: konfig.json)
-o, --output Output file path (default: karabiner.json)
-v, --version Display version number
-h, --help Display help message
Author:
Neeraj Dalal <[email protected]> (https://nrjdalal.com)
With Default Options
npx karabiner-human-configWith Custom Input and Output
You can use either/both of the options.
npx karabiner-human-config -i konfig.json -o karabiner.jsonTypes of Addressing
Comments
Don't hold back on the comments. They are your best friend. KHC will strip them out before generating the configuration.
Direct Keys
Use string values if there's only to event. In case of multiple events, use object values. Read more at specifying multiple events.
{
"hyper spacebar": "cmd spacebar",
"caps": { "t": "hyper", "a": "100 caps" }
}Group Keys
Instead of repeating the same key beginning, use group keys.
{
- "fn": { "t": "fn", "a": "cmd tab" },
- "fn spacebar": "cmd spacebar",
- "fn v": "$ open -a 'Visual Studio Code'",
+ "fn": {
+ "_self": { "t": "fn", "a": "cmd tab" },
+ "spacebar": "cmd spacebar",
+ "v": "$ open -a 'Visual Studio Code'"
+ }
}Note: Currently, _self is required to create a group key.
Application Group Keys
Use application names if you want to specify key mappings for a specific application. Don't worry about finding bundle identifiers, just use the app name.
{
"Visual Studio Code": {
"fn tilde": "ctrl tilde"
}
}Advanced Usage for From Events
Optional Modifiers
Use | to specify optional modifiers.
{
- "fn spacebar: "cmd spacebar"
+ "fn spacebar | any": "cmd spacebar"
}Generated: karabiner.json
{
"global": {
"show_in_menu_bar": false
},
"profiles": [
{
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"type": "basic",
"description": "fn spacebar | any",
"from": {
"key_code": "spacebar",
"modifiers": {
"mandatory": [
"fn"
],
"optional": [
"any"
]
}
},
"to": [
{
"key_code": "spacebar",
"modifiers": [
"left_command"
]
}
]
}
]
}
]
},
"name": "nrjdalal",
"selected": true,
"virtual_hid_keyboard": {
"keyboard_type_v2": "ansi"
}
}
]
}
Advanced Usage for To Events
Shell Command
Use $ to specify a shell command.
{
- "fn spacebar": "cmd spacebar"
+ "fn spacebar": "$ open -a 'Google Chrome'"
}Generated: karabiner.json
{
"global": {
"show_in_menu_bar": false
},
"profiles": [
{
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"type": "basic",
"description": "fn spacebar",
"from": {
"key_code": "spacebar",
"modifiers": {
"mandatory": [
"fn"
]
}
},
"to": [
{
"shell_command": "open -a 'Google Chrome'"
}
]
}
]
}
]
},
"name": "nrjdalal",
"selected": true,
"virtual_hid_keyboard": {
"keyboard_type_v2": "ansi"
}
}
]
}
Prefix Delay and Flags
Prefix with lazy, repeat, halt to set flags. Or number to specify a delay.
{
- "fn spacebar": "cmd spacebar"
+ "fn spacebar": "100 lazy repeat halt cmd spacebar"
}Generated: karabiner.json
{
"global": {
"show_in_menu_bar": false
},
"profiles": [
{
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"type": "basic",
"description": "fn spacebar",
"from": {
"key_code": "spacebar",
"modifiers": {
"mandatory": [
"fn"
]
}
},
"to": [
{
"lazy": true,
"repeat": true,
"halt": true,
"hold_down_milliseconds": 100,
"key_code": "spacebar",
"modifiers": [
"left_command"
]
}
]
}
]
}
]
},
"name": "nrjdalal",
"selected": true,
"virtual_hid_keyboard": {
"keyboard_type_v2": "ansi"
}
}
]
}
Specify Multiple Events
Instead of strings, use objects like { to: ..., to_if_alone: ... } to specify multiple to events.
{
- "fn spacebar": "cmd spacebar"
+ "fn": { "to": "fn", "to_if_alone": "cmd tab" }
}Generated: karabiner.json
{
"global": {
"show_in_menu_bar": false
},
"profiles": [
{
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"type": "basic",
"description": "fn",
"from": {
"key_code": "fn"
},
"to": [
{
"key_code": "fn"
}
],
"to_if_alone": [
{
"key_code": "tab",
"modifiers": [
"left_command"
]
}
]
}
]
}
]
},
"name": "nrjdalal",
"selected": true,
"virtual_hid_keyboard": {
"keyboard_type_v2": "ansi"
}
}
]
}
Alias
Custom Aliases
hyperforleft_command left_control left_option left_shiftleft_commandascmdlcmdl_cmdleft_cmdlcommandl_command
Check and add custom-aliases.ts for more.
Manipulator Key's Aliases
tfortoaforto_if_alonehforto_if_held_down
Check and add manipulator-keys.ts for more.
Future Considerations
- You tell me, I just got to know about Karabiner-Elements two days before publishing this on Feb 07, 2025.