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.
$ gem install karabiner
karabiner executable will be installed.
This gem provides only
karabiner dsl subcommand and other subcommands are delegated to original CLI for Karabiner.app.
1. Create ~/.karabiner
item "Command+G to open Google Chrome" do remap "Cmd-g", to: invoke("Google Chrome") end
2. Execute karabiner dsl command
$ karabiner dsl
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 ... end
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" end
If you want to add remap configuration, you have to call
In this example, Command+A will be remapped to Control+A.
You have to write "key expression" to specify keys to remap.
- any string without
+will be regarded as a single key
- strings are case insensitive
- any string without
- support system (consumer) keys
- words could be separated by space
- you can drop any key by using nil or the corresponding aliases
|Key combination||Regarded as||Notes|
||Control + A||
||Option + A||
||Shift + A (capital A)||if you write just
||Command + A|
||Command + Shift + A||you can use any combination of Ctrl, Opt, Shift, Cmd|
available single keys
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/iTerm.app") # Invoke the app of the specified path. end item "Copy date" do remap "Cmd-d", to: execute("date|pbcopy") end 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" end 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-]" end item "Window change in the same app" do remap "Opt-tab", to: "Cmd-F1" end
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.
- Fork it ( https://github.com/k0kubun/karabiner-dsl/fork )
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create a new Pull Request