~harmtemolder/karabiner-vim-mode-plus

A complex modification for Karabiner Elements that mimics Vim's navigation throughout your entire Mac
710b94ca — Harm te Molder 4 days ago
Update vim_mode_plus.json
1dc3fab3 — Harm te Molder 4 days ago
Add exceptions for Obsidian and imdone
58ebc210 — Harm te Molder 5 months ago
Add contributing to README.md

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~harmtemolder/karabiner-vim-mode-plus
read/write
git@git.sr.ht:~harmtemolder/karabiner-vim-mode-plus

You can also use your local clone with git send-email.

#Karabiner Vim Mode Plus

A complex modification for Karabiner Elements that mimics Vim’s navigation throughout your entire Mac.

#1. So what do you get?

#1.1 NORMAL mode

  • Activate with caps lock.
  • Deactivate with:
    • i or a (there are more like these, see below),
    • caps lock,
    • escape,
    • enter, which also sends an enter key press,
    • control+[,
    • Clicking any mouse button
    • Pressing any key within Atom, iTerm2, PyCharm or VSCodium (because those have their own Vim modes)
    • Pressing any key while having at least one finger on your trackpad

Alternatively you can hold caps lock for NORMAL mode and release it to exit.

Within NORMAL mode you can then move around with:

key action
h Move cursor left*
j Move cursor down*
k Move cursor up*
l Move cursor right*
e Move cursor to next end of word
b Move cursor to previous start of word
0 Move cursor to start of line (before any tabs)
^ Move cursor to start of line (after any tabs)
$ Move cursor to end of line
g,g Move cursor to start of document
G Move cursor to end of document
{ Move cursor to start of paragraph
} Move cursor to end of paragraph

*These work with shift, control, option and/or command, e.g. for hotkeys within apps.

Combine those with d, y and c to delete (“cut”), yank (“copy”) or change (“cut” and exit NORMAL mode) like so:

key action
d,d / y,y / c,c Delete/yank/change the entire line
d,e / y,e / c,e Delete/yank/change to the next end of word
d,b / ... / ... Delete/yank/change to the previous start of word
... Ditto for all other navigation keys mentioned above

Also:

key action
x Delete forward
X Delete back
p or P Paste at cursor
u Undo
control+r Redo

To exit NORMAL mode at specific locations:

key action
i Exit NORMAL mode at the cursor
I Exit NORMAL mode at the start of the line
a Exit NORMAL mode at the cursor
A Exit NORMAL mode at the end of the line
o Exit NORMAL mode on a new line below the cursor
O Exit NORMAL mode on a new line above the cursor

I’ve also mapped 3 keys to F18, F19 and F20, which I pick up on within Hammerspoon to load specific modals:

key action
s Activate Hammerspoon screen modal
m Activate Hammerspoon Markdown modal
spacebar Activate Hammerspoon hyper modal

#1.2 VISUAL mode

From within NORMAL mode you can switch to VISUAL mode with v. (Unfortunately you cannot switch to the other end of the selection with o as you normally would, so choose your starting point wisely.)

key action
v Exit VISUAL mode, enter NORMAL mode
h Select left
j Select down
... Ditto for all other navigation keys mentioned above
d Delete (“cut”) the selection and enter NORMAL mode
y Yank (“copy”) the selection and enter NORMAL mode
c Change (“cut”) the selection and exit Vim Mode entirely
x Remove the selection and enter NORMAL mode

#2. Setting up

  1. Install Karabiner. (I used this Homebrew cask through brew cask install karabiner-elements.)

  2. Import this complex modification straight into Karabiner through this link:

    karabiner://karabiner/assets/complex_modifications/import?url=https://git.sr.ht/~harmtemolder/karabiner-vim-mode-plus/blob/master/vim_mode_plus.json

    (You might have to copy and paste it into your browser’s address bar if your browser does not render it as a clickable link.)

#3. Making changes

I write my complex modifications in YML files, converting them into JSON using yml-to-json.py. You don’t have to, but you can, if you want to. Either way, make sure to remove and re-add all parts of this mod in Karabiner’s “Complex modifications” tab after making changes. The order they are in is important.

#4. Contributing

If you’ve made changes that you’d like to contribute to this repository, please use git send-email to post a patch to ~harmtemolder/karabiner-vim-mode-plus@lists.sr.ht. Follow this tutorial to learn how to use git send-email.

See the mailing list for previous patches.

#5. Reporting issues

If you encounter any issues, please report them here. (If you need help with sourcehut’s issue tracker, see this man page.) I’d also love to hear additions you would like to see to this setup. And feel free to contribute.