karaml 🍮

karaml (Karabiner in yaml) lets you write and maintain a
virtual layers-based Karabiner-Elements keyboard customization
configuration in YAML. It uses Python to translate the YAML into
Karabiner-compatible JSON.

karaml is based on the philosophy of mxstbr's
layer-centered Karabiner config, and my
thanks goes to to mxstbr and
yqrashawn for the inspiration for this
project. Immense thanks to tekezo for
Karabiner-Elements (consider
sponsoring/donating).

# Default layer, does not require activation
/base/:
  caps_lock: [escape, /nav/]  # Escape when tapped, /nav/ layer when held
  # Separate modifiers and keycodes with a pipe `|`
  # Lowercase modifiers = left, uppercase = right
  oc | n: /nav/               # Tap left opt + left ctrl + n to toggle /nav/
  O  | w: <o-backspace>       # right opt + w to left opt + Backspace

  # Enter when tapped, Left Control when held, lazy flag, any optional modifiers
  (x) | enter:
    - enter
    - left_control
    - null # No event when released
    - [+lazy]

  j+k: [escape, button1] # j+k to escape when tapped, left click when held

  # option (either side) + o/O to create new line below/above
  a | o: m |right + return
  a | O: up + m | right + return

  a | h: string(hello world) # Send multiple chars without concatenating with +

  # backspace/left on tap, MacOS/Kitty hints on hold/release, depending on frontmost app
  c | h: {
      # Notification with Karabiner-Style popup
      unless Terminal$ kitty$:
        [backspace, "notify(idh, My MacOS Shortcut Hints)", "notifyOff(idh)"],
      # Notification with AppleScript popup
      if Terminal$ kitty$: [left, "shnotify(My Kitty Shortcuts, ==Kitty==)"],
    }

  # Other syntax for modifiers is also supported
  ms   a: app(Alacritty) # left_command + left_shift + a to launch Alacritty
  <ms-c>: app(CotEditor) # left_command + left_shift + c to launch CotEditor

  # You can use Unicode symbols for modifiers instead of letters
  ⌘ ⇧    | g: string(lazygit)    # command + shift + g to send string 'lazygit'
  ⌃› ‹⌥  | s: string(git status) # right_control + left_option + s to send string 'git status'
  ☆      | o: /open/             # hyper + o to toggle /open/ layer

  # Utilize user-defined aliases
  tab  : [tab, ⁙]      # tab to left opt, ctrl, and shift when held
  ⁙ | ⏎: screen_saver  # left opt, ctrl, shift, and enter starts screen saver

  # Utilize user-defined templates
  ⌘ ⇧ | f: rectangle(fullscreen)

# condition 'nav_layer' must be true for the following maps
/nav/:
  (x) | h: left # vim navigation with any optional mods
  (x) | j: down
  (x) | k: up
  (x) | l: right

  s: [app(Safari), /sys/]     # Launch Safari on tap, /sys/ layer when held
  g: open(https://github.com) # Open link in default browser

# etc.
? /sys/
  System Layer
: # ↑ inserts a description for the layer into karabiner.json

  o | m: [mute, null, mute] # To mute if held/key down, unmute if released/key up
  k  : play_or_pause
  "}": fastforward
  u  : shell(open -b com.apple.ScreenSaver.Engine) # Start Screen Saver

# User defined aliases
aliases:
  ⁙: ⌥ ⌃ ⇧
  ⏎: return_or_enter
  screen_saver: shell(open -b com.apple.ScreenSaver.Engine)

# User defined templates
templates:
  rectangle: open -g "rectangle-pro://execute-action?name=%s"


# JSON integration - any Karabiner JSON can be added here
json:
  - {
      description: "Right Shift to ) if tapped, Shift if held",
      from: { key_code: right_shift },
      to: { key_code: right_shift, lazy: true },
      to_if_alone: { key_code: 9, modifiers: [shift] },
      type: basic,
    }

✨ Features

• Complex modifications on a single line of YAML so you can create and update keymaps quickly
• Events for when a key is tapped, held, and released defined by position in an
  array (rather than k/v pairs)
• Simple schema for requiring mandatory or optional modifiers in a pseudo-Vim
  style
• Multiple frontmost-app conditional remaps in a single YAML map
• Aliases for symbols, shifted keys, and complex names (e.g.
  grave_accent_and_tilde → grave, left_shift + [ → { )
• Define your own aliases for keycodes and modifiers!
• Template for app launchers, shell commands,
  notifications, and more by default
• Define your own templates for shell commands!
• Accepts regular Karabiner JSON in an 'appendix' table so all cases Karaml
  can't or doesn't plan to handle can still be in one config
• Automatically update your karabiner.json or write to the complex
  modifications folder and import with the Karabiner GUI - no need to handle
  any files other than your .yaml config
• Checks and formatting hints for your .yaml file - karaml will try not to
  let you upload a config that doesn't create a working modification, and tell
  you why (no more hunting for typos or missing/extraneous commas in a large JSON object)

❓ Why this project

The karabiner.json file can be hard to manage and visualize as it grows, as
the JSON format requires a lot of lines, carefully managed opening and closing
quotes, brackets, and commas, and repetitive conditional logic.

karaml tries to simplify this by providing a more readable, maintainable,
and easy to adjust format in YAML. This means making some trade-offs in
completeness of features, but I try to come close with the goal of balancing
features and configuration simplicity. To prevent the need for maintaining
multiple configurations if karaml falls short of your needs, karaml also
supports an 'appendix' table for any Karabiner-compatible JSON that can't be
expressed in karaml.

Why YAML?

• Easy to maintain: no mandatory quotes, but quotes can simplify escaping
  troublesome characters; minimal or no use of brackets around keys/values
• Easy to learn and easy to read
• A superset of JSON which allows us to fall back to JSON if wanted/needed
• Lets you leave comments for descriptions or notes to yourself!

⚡️ Quickstart

If you're unfamiliar with YAML, take a look at this handy
guide.

After installing, take the sample YAML
configuration and use it as a template for
your own. The sample config has comments to explain karaml syntax.

For more detailed explanations, follow the configuration
guide and read the YAML
Configuration section of this document.

For a cleaner, less commented on example, see one of my configurations
here. Follow the usage instructions
below to convert your karaml config to Karabiner-JSON with the command-line
tool (written in Python).

⚙️ YAML Configuration

Basic Mapping and Layer Structure

All keys belong to a layer. At minimum, a map requires a from: to structure
and must be in a layer:

/layer_name/:
  from_key: to_key

This is equivalent to:

{
  "from": { "key_code": "from_key" },
  "to": { "key_code": "to_key" } "type": "basic",
  "conditions": [ { "name": "layer_name_layer", "type": "variable_if", "value": 1 } ]
}

In your karaml config, you need to add a /base/ layer, but only as a matter
of convention. Maps in the /base/ layer don't check for conditions.

To add additional events or options to your maps, put them in a YAML array or
sequence.

/layer_name/: # All mappings below require the 'layer_name' layer enabled
  from_key(s): [when_tapped, when_held, when_released, [to_opts], { params }]

As shown above, you can add as many or as few items to the array as you like.

Enabling Layers

In the 'to' part of the map, enable layers with /layer_name/. In the first
position, the layer will be tap-toggled by the 'from'. In the second position,
the layer will be enabled when the 'from' key is held.

/base/:
  oc | n: /nav/ # enabled/disabled on tap
  caps_lock: [escape, /nav/] # enabled when held

# The maps indented in this layer will only work when the layer is enabled
/nav/:
  h: left
  j: down
  k: up
  l: right

Modifiers

To add modifiers to a primary key, follow the format <modifiers-primary_key>.
Wrap optional modifiers in parens.

To add modifiers to a primary key, there are a few available formats. The
general format is to have modifiers followed by a delimiter followed by
primary keys. Multiple modifiers can have whitespace between them if they
help readability, or they can be joined without any whitespace. Optional
modifiers are indicated by wrapping them in parens.

The original format for modifiers was <modifiers-primary_key>, but others
have been added to give the user a choice in whatever format they find most
readable.

The following are all examples of the mapping for left_control +
left_shift + a to open the Terminal app:

/base/:
  <cs-a>   : app(Terminal)  # A vim-ish syntax
  cs-a     : app(Terminal)  # Angle brackets are optional
  c s  - a : app(Terminal)  # Whitespace is flexible
  c s  | a : app(Terminal)  # Use a pipe or a dash as delimiter
  c s    a : app(Terminal)  # Or use the final whitespace as the delimiter
  'c s | a': app(Terminal)  # Quotes may help you with escape characters

The guides and the remainder of the README (mostly) use the
modifiers | primary_key format, with the pipe char | as the delimiter.

Whether the optional set in parens comes first or last doesn't matter, e.g.
(c)os | g and os(c) | g are both valid. But a single set of optional
modifiers in parens must be to the right or left of all mandatory modifiers
(if there are any mandatory modifiers).

Single letters are one way of specifying modifiers. Left side modifiers use
lowercase, right side modifiers use uppercase.

Examples:

• c | h → left_ctrl + h
• (x) | h → h (with any optional modifiers)
• mOC(s) | h → left_cmd + right_opt + right_ctrl + left_shift (optional) + h
• (s)mOC | h → (same as above)
• g(arh) | h → cmd (mandatory) + option + control + shift (optional) + h
• (arh)g | h → (same as above)

The mnemonics for the less-obvious modifiers are:

• m: Mac
• r: contRol
• h: sHift
• a: Alt
• g: Gui

An alternative system for modifiers uses Unicode symbols: ⌘ ⌥ ⌃ ⇧
The Unicode symbols ‹ and › denote left and right side modifiers.

Examples:

• ⌘ ⇧ | g → command + shift + g
• ⌘ (⇧) | g → command + shift (optional) + g
• ‹⌃ | h → left_ctrl + h
• ⌃› ‹⌥ | h → left_opt + right_ctrl + h

Of course you can use another valid syntax for the Unicode characters as well,
e.g. <⌘⇧-g> or ⌘⇧ g, etc.

If you need an easy way to type these Unicode characters, you can use a
text-expander or snippet tool like Typinator, the built in expanders in Raycast
or Alfred, TextExpander, etc. Or, set your own alias with the user-defined
aliases feature.

Or, see this suggestion in this Karabiner issue.

Key-Code Aliases

You can follow the explicit mapping for any key (e.g. s | 1 → !), or use
these available aliases. Be mindful in your YAML config that some characters
need to be escaped or wrapped in quotes to be recognized as strings.

Mutli-Modifier aliases:

MISSING ALIASES:

• +, since it's used to join multiple key codes and I need
  to figure out a way around that. Use plus in the meantime
• kp+ for the same reason, so use kpplus as an alternate

Defining your own aliases

You can define your own aliases for singular events by adding a top level
key named aliases anywhere in your config file. This YAML map will be merged
with the default aliases.

An alias has the following format:

aliases:            # Include this top-level key anywhere in your config
  alias_name: /{modifiers (optional)} {delimiter (optional)} {key_code}/

Example:

aliases:

  # No modifier
  ⏎: return_or_enter
  screen_saver: shell(open -b com.apple.ScreenSaver.Engine) # Start Screen Saver
  # With modifiers (any of the following)
  tilde: s | grave_accent_and_tilde  # left_shift + grave
  tilde: ⇧ | grave_accent_and_tilde  # left_shift + grave

  ⁙: o c | s  # With an explicit delimiter (`|` or `-`), the final `s` is
              # interpreted as the # key code it represents,
              # So this is an alias for `left_option` + `left_control` + `s`

  ⁙: o c s    # Without an explicit delimiter, this alias is all mods, since
              # `s` is one of the single-character modifier aliases.
              # So this is an alias for `left_option` + `left_control` + `left_shift`

  ⁙: ⌥ ⌃ ⇧    # An alias of all modifier symbols is added to the modifier
              # alias dict regardless of its syntax

/base/:
  ⌘ | ⏎: app(WezTerm)
  tilde: '`'
  '`'  : tilde
  ⁙ | ⏎: screen_saver

/sys:
  m | s: screen_saver

In the above example, the Unicode character ⏎ can be used as an alias for
return_or_enter, and tilde can be used as an alias for a tilde ~
character, and screen_saver is aliased to a shell command to enable the
screen saver.

Now these can be used in any layer in the config. In the example,
⌘ | ⏎ (return_or_enter with the command modifier) is used to launch
WezTerm, and tilde key's usual function has been reversed so that now you
have to press shift + the backtick character to get a backtick instead of vice
versa. And finally, the left_command and s key combination is used to start
the screen saver if the /sys/ layer is active.

Above, ⁙ is an alias for left_option + left_control + left_shift that
we can use as a modifier. In the /base/ layer, we use it and the ⏎ alias
for return_or_enter to make a rule for starting the screen saver, which also
uses the alias screen_saver that we defined above. It's a rule composed
entirely of user-defined aliases!

The purpose is to let you visualize your config in whatever way you find most
readable. Say for example you're creating a layer for your window-management
commands. Instead of a messy series of mappings like <coms-1>, <coms-2, or
a series of long and similar shell commands, now you can create aliases like
window_eights, window_center, move_to_space_1 etc. This makes for a
cleaner config and makes it easier to manage when you want to change the
keybindings.

Currently, only single-character aliases for modifier aliases are supported.
We're working on a way to support multi-character aliases for modifier aliases!

Rules for defining your own modifier aliases

If all the key codes in an alias are valid modifiers, then the alias may be
treated as a (multi-)modifier alias and added to the dict of modifiers aliases.

If the alias is composed entirely of modifier symbol characters (⌥, ⌘, ⇧,
⌃, etc.), then it will be added to the dict of modifier aliases, regardless of
the syntax used to define it.

If the alias is composed entirely of single characters that are all valid
modifier aliases (see the modifiers section), AND there are no
explicit delimiters in the alias definition, then it will be added to the dict
of modifier aliases. Otherwise, the final character will be treated as the
key code it represents. See the examples above.

Simultaneous from-keys, multiple to-events, requiring multiple layers

To get simultaneous from events or multiple to events, i.e. in Karabiner-JSON:

{
  "from": {
    "simultaneous": [{ "key_code": "j" }, { "key_code": "k" }]
  },
  "to": [{ "key_code": "h" }, { "key_code": "l" }]
}

Join valid key codes or aliases in any part of the YAML map with a +. This is
'whitespace agnostic', so j+k, j + k, and j+k + l etc. are all valid.

/base/:
  j+k: h+l
  c | j + k: [escape, "/nav/ + notify(idn, Nav Layer on!)", "notifyOff(idn)"]

This also applies to joining layers if you want to enable two layers at once.
Note that whichever layer comes later in the config will take priority if
there are conflicting keys. In the following example, the s of the /sys/
layer will take priority over the s of the /fn/ layer, and the
non-conflicting keys will all work as intended.

/base/:
  <a-caps_lock>: [null, /fn/ + /sys/]
/fn/:
  a: f1
  s: f2
  d: f3
/sys/:
  e: volume_down
  r: volume_up
  s: app(System Preferences)

Alternatively, for sending multiple singe characters, you can use string().
See: string special event function

Templates for common actions

karaml provides some templates for common-use actions. Some are just
to.shell_command
events in disguise. You can define your own templates for shell scripts - see
user-defined templates

You can use these as if they were to.events, e.g.:

/base/:
  o | g: open(https://github.com)

App Launchers

app(app_name)

Pass an app name (as it appears in your Applications folder) as an argument to
app(). I like using these in my /nav/ layer for quick access, but you might
want these in a standalone /apps/ layer.

/nav/:
  f: app(Firefox)

Open Browser Link

open(url)

Open a URL with your default browser.

/base/:
  o | g: open(https://github.com)

Shell Commands

shell(shell command)

Pass a shell
command
as an argument to shell(). This is what the app() and open() 'functions' are
actually doing under the hood. Please suggest other useful shorthands of shell
commands that we could add!

/sys/:
  grave: shell(open ~)

Input Sources

input(lang_regex)
input({"language": "regex", "input_source_id": "regex", "input_mode_id": "regex" })

Either pass a language regex as an argument to input() to select the first
available input source that matches the regex, or pass a string representing a
JSON object with all the valid Karabiner fields as specified
here.

/sys/:
  o | k + e:
    input(en) # Set English input source
    # Set a Greek keyboard based on source id
  o | k + g:
    'input({
    "input_source_id": "com.apple.keylayout.GreekPolytonic",
    "language": "el"
    })' # note the use of single quotes around the rhs to escape
    # double quotes and commas

Mouse Movement

mouse(action, speed|multiplier)

Using the to.mouse_key
event,
you can pass a two arguments that represent a key/value pair of movement/speed,
or the speed_multiplier key and its multiplier value. If you want to assign
multiple mouse events to the mapping, you can pass a string representing a JSON
object matching the Karabiner specs, just like with input sources.

/mouse/:
  m: mouse(x, -2000)
  n: mouse(y, 2000)
  e: mouse(y, -2000)
  i: mouse(x, 2000)
  c | m: mouse(horizontal_wheel, 100)
  c | n: mouse(vertical_wheel, -100)
  c | e: mouse(vertical_wheel, 100)
  c | i: mouse(horizontal_wheel, -100)
  s: mouse(speed_multiplier, 2.5)

Set Mouse Cursor Position

mousePos(x, y, screen)

Wraps around the to.software_function.set_mouse_cursor_position
event. The x and y arguments are mandatory, the screen argument is
optional, and all three must be integers. The screen argument is the screen
number, starting from 0. If you don't specify a screen, the cursor will be
moved to the same screen as the current mouse position.

/mouse/:
  "0": mousePos(0, 0)
  ⌥ | 2: mousePos(500, 500, 1)

Notifications (Karabiner Style)

notify(id, message)
notifyOff(id)

Shorthand for to.set_notification_message

The id is the reference for updating the notification with the message on
subsequent calls.

/sys/:
  s:
    - app(System Preferences)
    - /sys/ + notify(sysNotification,"System Layer Enabled")
    - notifyOff(sysNotification)

There are a few ways to disable a notification. The easiest to use and remember
is to pass the notification id as the only arg to notifyOff().

notifyOff(id)

Otherwise, you can pass an empty string or null as the message arg to notify().

notify(id, null)
notify(id, "")

Notifications (AppleScript Style)

shnotify(msg, title, subtitle, sound)

shnotify({"msg": "message", "title": "title", "subtitle": "subtitle", "sound": "sound"})

Displays a notification using AppleScript by running a shell command in the
format:

osascript -e 'display notification "message" with title "title" subtitle "subtitle" sound name "sound"'

See the scriping documentation here.

There are two ways to pass arguments to shnotify(). The first is to pass
positional arguments in the order of message, title, subtitle, and sound.

/sys/:
  o | 1: shnotify(text) # message only
  o | 2: shnotify(text, title) # message and title
  o | 3: shnotify(text, title, subtitle) # message, title, and subtitle
  o | 4: shnotify(text, title, subtitle, sound) # message, title, subtitle, sound
  o | 5: shnotify(text, null, null, sound) # message and sound only

The second is to pass a string representing a JSON object with all the valid
AppleScript notification fields.

/sys/:
  o | 6: 'shnotify({
    "msg": "text",
    "title": "title",
    "subtitle": "subtitle",
    "sound": "sound"
    })'
  # With a dict, you can omit any fields you don't want to use
  o | 7: 'shnotify({"msg": "text", "sound": "sound"})'

See the sample configuration for an example with
keyboard input source switching.

Sound names can be found at /System/Library/Sounds/
For more advanced notifications, try terminal-notifier or alerter and pass the command as a shell() command.

Software Functions

softFunc( {"function name": nested_dict} )

Takes a string representing a JSON object with all the valid Karabiner fields
as specified
here.

/mouse/:
  "p+1": 'softFunc("set_mouse_cursor_position": {"x": 0, "y": 0, "screen": 0 })'

Sticky Modifiers

sticky(modifier, toggle)

Pass two arguments: the modifier to be held on the next keypress (must be a
valid modifier key code), and whether to toggle the modifier, turn it on, or
turn it off (on, off, or toggle).

/base/:
  ⌥ | ['right_shift: sticky(left_shift, toggle)', right_shift]
  ⌘ | ['right_shift: sticky(left_shift, on)', right_shift]
  ⌃ | ['right_shift: sticky(left_shift, off)', right_shift]

Strings

string(a string of valid key codes or aliases)

You could map a key to type out a string of characters using the + joining method, e.g. git checkout like so...

/base/:
  a | g: g+i+t+space+c+h+e+c+k+o+u+t

...but for simplicity, you can use string() (though the above method is valid):

/base/:
  a | g: string(git checkout )

The string must contain valid key codes or valid single-character aliases.
So, [, ?, a blank space for spacebar, etc. will get interpreted
as characters, and spacebar, kp-, left etc. will get interpreted as a
literal string of chars, not their alias counterparts.

You can use a combination if you want to send non-single character events:

/base/:
  a | g: string(git checkout main) + enter

Variables

The var() function takes two arguments: a variable name and a value (0 or 1).
See the to.set_variable
documentation

karaml intends variables to be handled as layers and automates some mappings
under the hood to streamline toggling and enabling layers, but the var()
function allows more granular control.

/base/:
  o | s:
    var(sys_layer, 1) # This does not automatically create a corresponding
    # toggle-off mapping. Don't get stuck in another layer!

User Defined Shell Command Templates

This feature copies much of the design of the template feature in
GokuRakuJoudo,
though not as fully featured.

You can define your own templates for shell commands in the templates section
of your configuration file. This may be useful if you want to create a lot of
maps for similar long and complex shell commands.

templates:
  template_name: "command template %s || another command %s"

/base/:
  ⌥ | 1: template(arg1, arg2)

All %s will be replaced by the arguments passed to any instances of a
template in your layers. You can have as many args as you want, but karaml
will check that the amount of args passed to a template instance matches the
amount of %s in the template definition.

As an example of a good use case, here is a template for triggering
Rectangle Pro actions using urls.

templates:
  rectangle: open -g "rectangle-pro://execute-action?name=%s"

/rectangle/:
  ⌘ ⇧ | 1: rectangle( fullscreen       )
  ⌘ ⇧ | 2: rectangle( left-half        )
  ⌘ ⇧ | 3: rectangle( right-half       )
  ⌘ ⇧ | 4: rectangle( next-display     )
  ⌘ ⇧ | 5: rectangle( previous-display )
  # etc.

This looks much cleaner than having a few dozen lines of the same long
command.

Note that the templates map in your configuration file is loaded BEFORE
your aliases map (regardless of where you place those maps in your config),
so you can use templates in your aliases, but you can't use aliases in your
templates.

templates:
  rectangle: open -g "rectangle-pro://execute-action?name=%s"

aliases:
  fullscreen : rectangle( fullscreen )
  left-half  : rectangle( left-half  )
  right-half : rectangle( right-half )

/rectangle/:
  ⌘ ⇧ | 1: fullscreen
  ⌘ ⇧ | 2: left-half
  ⌘ ⇧ | 3: right-half
  # etc.

Layer descriptions

If no description is provided for a layer, karaml will add a default one to the
karabiner.json file in the form of {layer name} layer. You can override
this by adding some text to your layer's key after the layer (or layers).

/mouse/     Mouse Movements:  # Excess whitespace is ignored
  m       : mouse(x, -2000)
  n       : mouse(y, 2000)
  e       : mouse(y, -2000)
  i       : mouse(x, 2000)

# Using YAML's complex-key syntax for multi-line keys
? /symnum/

  Numpad + Symbols Layer
:
  (x) j: "0"
  (x) k: ","

# Layers with multiple conditions can also be split across multiple lines
? /symnum/ +
  /nav/

  Sym & Nav Multi-layer
:
  m   : left
  n   : down
  e   : up
  i   : right

The parser will replace all the newline chars in the complex key with a space
and parse it as if it were a single line, as in the /mouse/ layer example.

This is an unconventional way to use YAML, but since a major part of karaml's
design is to make a compact Karabiner-Elements configuration file and avoid
dictionaries and excess brackets where possible and sensible,
this was a good compromise.

The advantage of this over simply adding YAML comments near the layer is that
the description makes it into the karabiner.json file and is displayed in
the Karabiner-Elements GUI.

NOTE: The only restriction on layer descriptions is that they must not
contain a forward slash (/). This was done to simplify the parsing of
muti-conditional layers. karaml will raise an error if it detects a forward
slash in a layer description.

Frontmost-App Conditions

To set frontmost-app conditions, the from-key part of your map remains the
same, but your value becomes a dictionary (instead of the usual single string
or list/sequence).

/layer/:
  from-key:
    {
      if regex regex ...: [when-tapped, when-held, etc.],
      unless regex regex ...: [etc.],
    }

The dictionary's keys must be in the form of either if regex regex ... or
unless regex regex ... where regex is a regex expression that matches the
bundle identifier of the app you want to match (read the Karabiner
docs
for more info). karaml will yell at you if your conditional term isn't if or
unless. Every following substring separated by a space will be interpreted
by karaml as a list (YAML supports lists in keys, but Python doesn't, so use
a string here).

The dictionary's values are your usual karaml map values. Each k/v pair
represents a new map that includes the frontmost_app_if/unless conditional.

You can create as many unique keys as you want here, all of which will be tied
to the original 'from' key. Mind your regex and your capitalization!

/base/:
  c | u: { unless Terminal$ iterm2$ kitty$: g-backspace }
  a | O: { unless Terminal$ iterm2$ kitty$: up + g-right + enter }
  a | o: { unless Terminal$ iterm2$ kitty$: g-right + enter }
  a | g: {
      # types 'git ' when tapped, 'checkout' when held if any of these apps are focused
      if Terminal$ iterm2$ kitty$: [string(git ), string(checkout)],
      if CotEditor$: g | l, # 'go to line' alternate shortcut if CotEditor is focused
    }

Global parameters

Add a parameters map to your .yaml file to set global parameters for your
profile. These parameters will be applied to all mappings in the profile unless
overridden by a mapping's own parameters object.

parameters:
  {
    "basic.to_if_alone_timeout_milliseconds": 100,
    "basic.to_if_held_down_threshold_milliseconds": 101,
    basic.to_delayed_action_delay_milliseconds: 150,
    "basic.simultaneous_threshold_milliseconds": 75,
    "mouse_motion_to_scroll.speed": 100,
  }

/base/:
  # ...

Profile Name and Complex-Modification Title

Add a profile map to your .yaml file to set the profile name and a title
map to set the complex-modification title. Both are optional, and you can leave
them in your config even if you don't use the profile-creation or the
complex-modification writing feature. If you don't provide either, karaml will
generate default placeholders before it writes the file.

# If a profile name is not provided, one will be generated from the
# current Unix timestamp
profile_name: Karaml Config

title: KaramlRules

JSON Extension Map

Add a json map to the .yaml file to include Karabiner-compatible JSON. This
is intended for cases where karaml doesn't support a feature you need, or when
you think the JSON looks easier to read than the karaml syntax, but you still
want to use karaml for the rest of your config.

Be mindful of the slight differences in syntax between YAML and JSON. Namely,
quotes are optional unless needed for escaping characters, elements of the
json map are separated as sequence item (a properly indented dash -
followed by a space), and no commas are used to separate those items.

WARNING!: in the layer mappings, karaml 'inspects' your configuration for
proper formatting - not just whether you wrote it in a syntax karaml can
intrepret, but also whether you used valid key codes, valid modifiers, etc.
Currently, karaml doesn't support these 'health checks' for the JSON extension map,
so karaml will just append whatever you put in there to the rule-set.

/base/:
  # ...

/nav/:
  # ...

json:
  - {
      # No need for quotes since there are no chars that need escaping
      description: Right Control to > if tapped and control if held,
      from: { key_code: right_control },
      to: { key_code: right_control, lazy: true },
      to_if_alone: { key_code: period, modifiers: [right_control] },
      type: basic,
    }
  - {
      # Quotes needed in the description because of the comma.
      # We can also add quotes just if we want to
      "description": "Left Control to < if tapped, control if held",
      "from": { "key_code": "left_control" },
      "to": { "key_code": "left_control", "lazy": true },
      "to_if_alone": { "key_code": "comma", "modifiers": ["left_control"] },
      "type": "basic",
    }

🐍️ Python backend for handling your files

The program reads your .yaml config with the PyYAML module, interprets your
layers and keybindings, checking that they are all well-formed along the way,
and creates 'KaramlizedKey' objects with all the relevant attributes (from
events, to events, options, modifiers, etc.) that are eventually converted into
Karabiner-compatible JSON.

karaml then either updates your existing karabiner.json file or your
complex-modifications folder.

• If you elect to update karabiner.json directly:
  • karaml makes a copy of the current karabiner.json file and adds that copy
    to ~/.config/karabiner/automatic_backups/ as
    karabiner.backup.TIMESTAMP.json, every time (thirty of my ~6000 line
    Karabiner JSON backups add up to ~10MB, so check in every once in a while)
  • karaml then searches the profiles list in karabiner.json for a profile
    name that matches the one in your config (or generates a new one if you
    didn't specify it - add one!). If it finds a match, it will replace that
    profile with the new config generated from the .yaml file, otherwise it
    just appends a new profile to the list
• If you elect to add your karaml config as a ruleset to the
  complex-modifications folder:
  • If you passed the -c flag in the command line, karaml expects a filename
    to write to. If you're using the CLI menu, karaml will default to
    creating/overwriting karaml_complex_mods.json. If the file already
    exists, you'll get a confirmation prompt. karaml doesn't backup your
    complex-mods files
  • If you have a title map in your .yaml file, karaml will use that as the
    title of your complex-modification ruleset. If you don't, karaml will title
    your ruleset as KaramlRules

🎨 About the Design

Understanding a standard Karabiner configuration is useful for leveraging the
most out of karaml, but at its core karaml is designed to reduce events to
either when_tapped and when_held actions (also when_released, but that's
automated when layers are enabled when held).

when_tapped is mapped to either to or to_if_alone, and when_held is
mapped to either to or to_if_held_down depending on whether the map enables
a layer, a modifier, or a notification ('non-chatty' events) when held.

karaml was designed around toggling layers or enabling modifiers when a key is
held down, and letting the key have some other function when tapped. I found
that, for my typing style, a 100ms to_if_alone_timeout_milliseconds setting,
mapping the 'when tapped' function to to_if_alone and the 'when held'
functions to a to dictionary (instead of to_if_held_down) provided
immediate switching between layers or enabling of modifier keys, since the to
dictionary doesn't wait for the to_if_held_down_threshold_milliseconds timeout. This means
sending the to event even when to_if_alone is sent , but so long as the
event is 'harmless', or not 'chatty', i.e. it is a layer, a modifier, or a
notification, and so long as we set the lazy opt when necessary (e.g. for my
mapping of enter → control when held), this doesn't cause any significant
side effects.

When a 'chatty' event would have side-effects, or when sending an event on 'if
held down' following the relevant parameters is an explicit goal (rather than
just a way of distinguishing a tap from a hold), karaml can handle that by
making the distinction between 'chatty/harmless' events and otherwise. In these
cases, karml will place the 'when-held' event in the to_if_held_down
dictionary to prevent 'chatter' caused by events in the to dictionary.

In short, karaml is opinionated about layers and modifiers, and is designed to
act with zero delay given that most maps can be handled by reaching another
layer via tap-to-toggle or hold-to-enable. With this in mind, it tries to
reduce the need to manually specify 'companion' mappings for layer toggling,
e.g. for an 'x sets y = 1 if variable y = 0' mapping, karaml will automatically
generate a 'x sets y = 0 if variable y = 1' mapping, and for 'x sets y = 1 if x
is held down', karaml will automatically generate 'x sets y = 0 if x is
released'.

I try to handle as many other cases as possible in a concise manner in the
karaml style, but as a fallback, a json: map can be added to the config to
integrate a regular Karabiner JSON config (with minor YAML modifications). In
fact, you could just use karaml as a way to write a regular Karabiner config in
YAML but with less commas and little to no quotation marks.

🔩 Requirements

• Python >= 3.10

This program was written while using Karabiner-Elements 14.11.0 and MacOS
12.5.1

📦 Installation

Clone this repo and install with pip in your terminal:

git clone https://github.com/al-ce/karaml.git
cd karaml
pip install .

🚀 Usage

After you've made a well-formed karaml config, open your terminal app.

The karaml command requires one positional argument: the name of the YAML
file with your karaml config in the current folder (or the relative/absolute
path to that file).

karaml my_karaml_config.yaml

If your karaml maps aren't mapped correctly, the program will raise an
exception and try to give you some information about what went wrong. The error
system needs improvement - working on it!

CLI prompt + modes

Without any optional arguments, you will be prompted to make a configuration
choice:

$ karaml my_karaml_config.yaml
Reading from: my_karaml_config.yaml...

1. Update karabiner.json with my_karaml_config.yaml
2. Update complex modifications folder with my_karamlconfig_.yaml.
Writes to: karaml_complex_mods.json
3. Quit

1. updates your karabiner.json file directly, either creating a new profile
or updating an existing one depending on the profile_name key in your config.
Before every update, karaml makes a backup copy of your previous
karabiner.json in the automatic_backups folder. This can add up! But I
didn't want to risk a bug in the program destroying your config.

2. writes a JSON file to your karabiner complex modifications folder which
you can import with the Karabiner-Elements GUI. Then you can enable or disable layers
individually, but you should enable them all at once to ensure your layer and mapping
priority is setup as intended. The file is named karaml_complex_mods.json by
default, but you can change this in your karaml config with the title key,
(and by doing so, you can easily switch between rulesets).

3. quits the program.

-k mode

By passing the -k flag, you will bypass the usual CLI prompt and karaml will
update your karabiner.json file directly (as always, creating a backup
beforehand).

karaml my_karaml_config.yaml -k

-c mode

By passing the -c flag, you will bypass the usual CLI prompt and karaml will
update your complex modifications folder directly. If you're updating an old
complex rule set, you'll have to remove the old complex modifications and
re-enable the updated ones, as you would normally. No backup files will be
created for complex modifications, but you will get a confirmation prompt to
confirm the overwrite/update. If you do not provide a title map in your YAML
config, karaml will default to writing/updating the 'Karaml rules' ruleset.

karaml my_karaml_config.yaml -c

-d (debug) mode

If there are malformed maps in your config, by default karaml prints you an
error message and quits without making any changes to karbiner.json.
By adding the -d flag, you can see the full stack trace of the error.
If you're making a map that should work, either because it's a feature you
think should be implemented or because you found a bug, please add the stack
trace in an issue!

🪲 Known Issues / Bugs / Limitations

• Can't toggle layer in 'when-tapped' position if also set in 'when-held'
  position (e.g. <a-f>: [/fn/, /fn/] only enables the /fn/ layer when held)
• from.simultaneous_options not yet supported (this one will be tricky)
• to_delayed_action not yet supported
• halt option for to_if_held_down and to_if_alone not yet supported
• Can't add multiple shell-based templates in one mapping (see this issue)

🌱 TODOs

• More condition types (device_if, etc.)
• More helpful configuration error messages

🔭 Alternatives

• @mxstbr's Karabiner configuration
  generator written in TypeScript
• Goku
• karabiner.ts