karabiner-human-config
Version:
The easiest way to write Karabiner-Elements configuration files, ever!
671 lines (580 loc) • 16.7 kB
Markdown
# Karabiner-Human-Config
## The easiest way to write Karabiner-Elements configuration files, ever!
[](https://www.npmjs.com/package/karabiner-human-config)
[](https://www.npmjs.com/package/karabiner-human-config)
[](https://github.com/nrjdalal/karabiner-human-config)
Find it on the official website of Karabiner-Elements at [external JSON generators](https://karabiner-elements.pqrs.org/docs/json/external-json-generators).
Creating configuration files for [Karabiner-Elements](https://github.com/pqrs-org/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](#comments).
- Can use [custom aliases](#custom-aliases) like `caps` `hyper` `cmd` `ctrl` etc.
- Can specify `t` `a` etc as [manipulator key's aliases](#manipulator-keys-aliases).
- Easily prefix [flags and delays](#prefix-delay-and-flags) like `100` easily, if needed.
- Use `$` for [shell command](#shell-command).
- Just use the [app's name](#application-group-keys) like `Visual Studio Code`.
```json
{
// 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:
```bash
npx karabiner-human-config
```
And voila! From 10-15 lines to 170+ lines of configuration in just a few seconds.
<details><summary>Generated: karabiner.json</summary><br/><pre>
{
"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"
}
}
]
}
</pre></details>
<br/>
The generated configuration will be saved in `karabiner.json` in the same directory.
<em>**Bonus: If you wish to checkout my personal configuration, you can find it [here](konfig.json).
And what it generates [here](karabiner.json).**</em>
<br/>
## Table of Contents
- [CLI Usage](#cli-usage)
- [With Default Options](#with-default-options)
- [With Custom Input and Output](#with-custom-input-and-output)
- [Types of Addressing](#types-of-addressing)
- [Comments](#comments)
- [Direct Keys](#direct-keys)
- [Group Keys](#group-keys)
- [Application Group Keys](#application-group-keys)
- [Advanced Usage for From Events](#advanced-usage-for-from-events)
- [Optional Modifiers](#optional-modifiers)
- [Advanced Usage for To Events](#advanced-usage-for-to-events)
- [Shell Command](#shell-command)
- [Prefix Delay and Flags](#prefix-delay-and-flags)
- [Specify Multiple Events](#specify-multiple-events)
- [Conditions](#conditions)
- [Per-Manipulator Conditions](#per-manipulator-conditions)
- [Group-Level Conditions](#group-level-conditions)
- [Conditions-Only Groups](#conditions-only-groups)
- [Alias](#alias)
- [Custom Aliases](#custom-aliases)
- [Manipulator Key's Aliases](#manipulator-keys-aliases)
- [Future Considerations](#future-considerations)
<br/>
## CLI Usage
```
Version:
karabiner-human-config.x.x
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 <admin.com> (https://nrjdalal.com)
```
### With Default Options
```bash
npx karabiner-human-config
```
### With Custom Input and Output
You can use either/both of the options.
```bash
npx karabiner-human-config -i konfig.json -o karabiner.json
```
<br/>
## 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](#specify-multiple-events).
```json
{
"hyper spacebar": "cmd spacebar",
"caps": { "t": "hyper", "a": "100 caps" }
}
```
### Group Keys
Instead of repeating the same key beginning, use group keys.
```diff
{
- "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.
```json
{
"Visual Studio Code": {
"fn tilde": "ctrl tilde"
}
}
```
<br/>
## Advanced Usage for From Events
### Optional Modifiers
Use `|` to specify optional modifiers.
```diff
{
- "fn spacebar: "cmd spacebar"
+ "fn spacebar | any": "cmd spacebar"
}
```
<details><summary>Generated: karabiner.json</summary><br/><pre>
{
"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"
}
}
]
}
</pre></details>
<br/>
## Advanced Usage for To Events
### Shell Command
Use `$` to specify a shell command.
```diff
{
- "fn spacebar": "cmd spacebar"
+ "fn spacebar": "$ open -a 'Google Chrome'"
}
```
<details><summary>Generated: karabiner.json</summary><br/><pre>
{
"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"
}
}
]
}
</pre></details>
### Prefix Delay and Flags
Prefix with `lazy`, `repeat`, `halt` to set flags. Or `number` to specify a delay.
```diff
{
- "fn spacebar": "cmd spacebar"
+ "fn spacebar": "100 lazy repeat halt cmd spacebar"
}
```
<details><summary>Generated: karabiner.json</summary><br/><pre>
{
"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"
}
}
]
}
</pre></details>
### Specify Multiple Events
Instead of strings, use objects like `{ to: ..., to_if_alone: ... }` to specify multiple to events.
```diff
{
- "fn spacebar": "cmd spacebar"
+ "fn": { "to": "fn", "to_if_alone": "cmd tab" }
}
```
<details><summary>Generated: karabiner.json</summary><br/><pre>
{
"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"
}
}
]
}
</pre></details>
<br/>
## Conditions
Add [Karabiner conditions](https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/) like `device_if`, `device_unless`, `input_source_if`, `variable_if`, `keyboard_type_if`, and more.
### Per-Manipulator Conditions
Use `c` (or `conditions`) to add conditions to a single manipulator.
```json
{
"caps": {
"t": "escape",
"c": [{ "type": "device_if", "identifiers": [{ "vendor_id": 1452 }] }]
}
}
```
### Group-Level Conditions
Use `_conditions` inside a group with `_self` to apply conditions to all manipulators in the group.
```json
{
"rcmd": {
"_self": "rcmd",
"_conditions": [
{
"type": "device_unless",
"identifiers": [{ "is_built_in_keyboard": true }]
}
],
"d": "$ open \"https://discord.com\""
}
}
```
Both `rcmd` (self) and `rcmd d` will have the `device_unless` condition applied.
### Conditions-Only Groups
Use `_conditions` without `_self` to scope conditions to a group of keys without a shared modifier.
```json
{
"external_keyboard": {
"_conditions": [
{
"type": "device_if",
"identifiers": [{ "vendor_id": 1234, "product_id": 5678 }]
}
],
"a": { "t": "b" },
"caps": { "t": "escape" }
}
}
```
The group key (`external_keyboard`) is just a label — child keys are processed as-is with the conditions inherited.
Note: `_conditions` also works inside [application group keys](#application-group-keys) to combine device conditions with app-specific conditions.
<br/>
## Alias
- [key_codes by Karabiner-Elements](https://github.com/pqrs-org/Karabiner-Elements/blob/main/src/apps/SettingsWindow/Resources/simple_modifications.json)
### 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](constants/custom-aliases.ts) for more.
### Manipulator Key's Aliases
- `t` for `to`
- `a` for `to_if_alone`
- `h` for `to_if_held_down`
- `c` for `conditions`
Check and add [manipulator-keys.ts](constants/manipulator-keys.ts) for more.
<br/>
## Future Considerations
- You tell me, I just got to know about Karabiner-Elements two days before publishing this on Feb 07, 2025.