A human-readable configuration generator for Karabiner-Elements

[nrjdalal]

Hi guys,

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 caps hyper cmd ctrl etc.
• Specify t a etc as manipulator key's aliases.
• Prefix flags and delays like 100 easily, 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-config

And 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
  • With Default Options
  • With Custom Input and Output
• Types of Addressing
  • Comments
  • Direct Keys
  • Group Keys
  • Application Group Keys
• Advanced Usage for From Events
  • Optional Modifiers
• Advanced Usage for To Events
  • Shell Command
  • Prefix Delay and Flags
  • Specify Multiple Events
• Alias
  • Custom Aliases
  • Manipulator Key's Aliases
• 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-config

With Custom Input and Output

You can use either/both of the options.

npx karabiner-human-config -i konfig.json -o karabiner.json

Types 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

• key_codes by Karabiner-Elements

Custom Aliases

• hyper for left_command left_control left_option left_shift
• left_command as cmd lcmd l_cmd left_cmd lcommand l_command

Check and add custom-aliases.ts for more.

Manipulator Key's Aliases

• t for to
• a for to_if_alone
• h for to_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.