Lightweight keyremap configuration DSL for Karabiner
Latest commit 638a011 Dec 4, 2016 1 @ardecvz ardecvz committed on GitHub Mention most combinations work out-of-box

Karabiner DSL Build Status

Lightweight keyremap configuration DSL for Karabiner

Why Karabiner DSL?

Original Karabiner's configuration is very hard to write.
Karabiner DSL is its wrapper, which is easy-to-write and readable.

If you write Karabiner's config with Karabiner DSL, you can update your keyremap configuration quickly.


First of all, you have to install Karabiner. Karabiner is a keyboard remap utility for Mac OSX.

Then execute:

$ gem install karabiner

Then karabiner executable will be installed. This gem provides only karabiner dsl subcommand and other subcommands are delegated to original CLI for


1. Create ~/.karabiner

item "Command+G to open Google Chrome" do
  remap "Cmd-g", to: invoke("Google Chrome")

2. Execute karabiner dsl command

$ karabiner dsl

Then karabiner dsl will update Karabiner's config as you expected.

3. Enable your favorite configurations


How to write ~/.karabiner


karabiner-dsl's DSL is a superset of Ruby.
So you can use any Ruby methods in ~/.karabiner.


item "configuration unit" do

In karabiner-dsl, any Karabiner's configuration unit is expressed in item and its do ~ end block.
You can group some remap configurations in one item and enable them in one click.


item "remap example" do
  remap "Cmd-a", to: "C-a"

If you want to add remap configuration, you have to call remap method.
In this example, Command+A will be remapped to Control+A.

You have to write "key expression" to specify keys to remap.

key expression

  • a, A, 1, ;, tab, Tab, space, up, down
    • any string without - or + will be regarded as a single key
    • strings are case insensitive
  • Volume Mute, Mute, Brightness Down, Brightness_Down
    • support system (consumer) keys
    • words could be separated by space or underscore _
  • nil, nil, none
    • you can drop any key by using nil or the corresponding aliases

key combination

Key combination Regarded as Notes
C-a, Ctrl-a, C+a, Ctrl+a Control + A C- is a short alias for Ctrl-
M-a, Opt-a, Alt-a, M+a, Opt+a, Alt+a Option + A M- and Alt- are aliases for Opt-
Shift-a, Shift+a Shift + A (capital A) if you write just A, it will be regarded as small a
Cmd-a, Cmd+a Command + A
Cmd-Shift-a, Cmd+Shift-a, Cmd-Shift+a, Cmd+Shift+a Command + Shift + A you can use any combination of Ctrl, Opt, Shift, Cmd

available single keys

Karabiner DSL keycode and alias reference

Karabiner full keycode reference

Note: Karabiner DSL is designed to work with all keycodes which are supported by Karabiner (listed in the full keycode reference).

a b c ... x y z
0 1 2 ... 7 8 9

F1 F2 ... F11 F12
\ [ ] ; ' ` , . / - =
Up Down Right Left
Space Tab Delete ... Forward_Delete Esc Capslock
Mute Volume_Down Volume_Up ... Prev Play Next

nil none

Ctrl_R  Ctrl_L
Opt_R   Opt_L   Alt_R   Alt_L
Cmd_R   Cmd_L
Shift_R Shift_L


item "Application shortcuts" do
  remap "C-o", to: invoke("YoruFukurou") # Invoke the app under the /Applications.
  remap "C-u", to: invoke("Google Chrome") # ditto.
  remap "C-h", to: invoke("/Users/johndoe/Applications/") # Invoke the app of the specified path.

item "Copy date" do
  remap "Cmd-d", to: execute("date|pbcopy")

item "Control+PNBF to Up/Down/Left/Right" do
  remap "C-p", to: "Up"
  remap "C-n", to: "Down"
  remap "C-b", to: "Left"
  remap "C-f", to: "Right"

appdef "HIPCHAT", equal: "com.hipchat.HipChat"
item "HipChat Room Change", only: "HIPCHAT" do
  remap "Cmd-K", to: "Cmd-Shift-["
  remap "Cmd-J", to: "Cmd-Shift-]"

item "Window change in the same app" do
  remap "Opt-tab", to: "Cmd-F1"

Linux alternative

You could achieve the same functionality on Linux/X11 with a sister project xkremap. It has a similar syntax and doesn't need any Ruby interpreter to run.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request