How to configure Home Row Mods with KMonad on macOS

README.md

Intro

Karabiner and KMonad are great open source software. Don't forget to support the authors and contributors.

If you want to try home row mods on OSX, don't use Karabiner but KMonad. KMonad is harder at the beginning but then it is easier than Karabiner. Creating layers in KMonad is trivial and without drawbacks, while it is impossible in Karabiner without drawbacks.

You need to compile a PR of the project. Install https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/releases/download/v2.1.0/Karabiner-DriverKit-VirtualHIDDevice-2.1.0.pkg

Install 
/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

git clone --recursive https://github.com/vosaica/kmonad.git
cd kmonad
git checkout Upgrade-DriverKit-VirtualHIDDevice
git submodule update --init
stack build --flag kmonad:dext --extra-include-dirs=c_src/mac/Karabiner-DriverKit-VirtualHIDDevice/include/pqrs/karabiner/driverkit:c_src/mac/Karabiner-DriverKit-VirtualHIDDevice/src/Client/vendor/include

You need to see the virtual keyboard. Try to restart OSX if it doesn't appear.

Debug

I use KeyCastr to have visual feedback

Skip sudo password

# create a new file for writing - visudo uses the vim editor by default.
# go read about this if you have no idea what is going on.

sudo visudo -f /private/etc/sudoers.d/kmonad

# input the line below into the file you are editing.
#  replace <kmonad> with the path to the kmonad binary (output of: which kmonad).
#  replace <user> with your username (output of: whoami). 
#  replace <hash> with the sha256 hash of the kmonad binary (output of: shasum -a 256 $(which kmonad)).
#   this hash must be updated manually after running brew upgrade.

<user> ALL=(root) NOPASSWD: sha256:<hash> <kmonad>

• Reference https://github.com/koekeishiya/yabai/wiki/Installing-yabai-(latest-release)#configure-scripting-addition

If it works

If it works, this will be the output

❯ sudo kmonad .kmonad.kbd
connected
driver_loaded 0
driver_version_matched 0
driver_loaded 1
driver_version_matched 1

Bugs

1. The european MBP keyboard is not recognized correctly and this symbol (§) makes kmonad quit with this error.

Encountered error in KeySource: [Cannot translate from mac keycode: (7,100)]
kmonad: [Cannot translate from mac keycode: (7,100)]

2. Suspend breaks kmonad and it needs to be restarted. I keep Activity Monitor around to kill kmonad with the mouse.

References

• kmonad/kmonad#716
• pqrs-org/Karabiner-Elements#3559 (comment)
• https://sokinpui.github.io/Blog/post/kmonad-introduction/
• https://www.youtube.com/watch?v=Dhj1eauljwU
• https://precondition.github.io/home-row-mods

kmonad.kbd

(defcfg
  input  (iokit-name)
  output (kext)

  ;; Comment this if you want unhandled events not to be emitted
  fallthrough true

  ;; Set this to false to disable any command-execution in KMonad
  allow-cmd true
)

;; lmet -> cmd
;; lalt -> option
;; fn   -> fn


(defalias
    sft_a (tap-hold-next-release 200 a lsft)
    alt_s (tap-hold-next-release 200 s lalt)
    ctl_d (tap-hold-next-release 200 d lctl)
    met_f (tap-hold-next-release 200 f lmet)

    met_j (tap-hold-next-release 200 j rmet)
    ctl_k (tap-hold-next-release 200 k rctl)
    alt_l (tap-hold-next-release 200 l lalt)
    sft_; (tap-hold-next-release 200 ; rsft)

    nav (layer-toggle nav)
    m_q (around lmet q)
    m_w (around lmet w)
    m_e (around lmet e)
    m_r (around lmet r)
    m_t (around lmet t)
    m_a (around lmet a)
    m_s (around lmet s)
    m_d (around lmet d)
    m_f (around lmet f)
    m_g (around lmet g)
    m_z (around lmet z)
    m_x (around lmet x)
    m_c (around lmet c)
    m_v (around lmet v)
    m_sp (around lmet space)

    sub (layer-toggle sublime)
    sm_sp (around lmet P)
)

(defsrc
  f10  f11  f12
  tab  q    w    e    r    t    u    i    o    p
  caps a    s    d    f    g    h    j    k    l    ;
  lsft z    x    c    v    b    n    m    ,    .    /
  fn lctl lalt lmet space
)

(deflayer qwerty
  mute vold volu
  tab  q    w    e    r    t    u    i    o    p
  lctrl @sft_a   @alt_s   @ctl_d   @met_f   g   h   @met_j   @ctl_k   @alt_l   @sft_;
  lsft  z    x    c    v    b    n    m    ,    .    /
  fn lctl lalt @nav space
)

(deflayer nav
  _ _ _
  tab   @m_q   @m_w   @m_e   @m_r    @m_t    {      }    \(    \)
  lctrl @m_a   @m_s   @m_d   @m_f    @m_g   left  down   up   right  ;
  @sub  @m_z   @m_x   @m_c   @m_v      b     n      [     ]     <    >
  fn lctl lalt @nav @m_sp
)

;; cmd-shift-p
(deflayer sublime
  _ _ _
  _     _      _      _      _       _      _     _      _    @sm_sp
  _     _      _      _      _       _      _     _      _       _       _
  _     _      _      _      _       _      _     _      _       _       _
  _     _      _      _      _
)

I'm having a problem not sure if someone else notices it.
For all the keys with the tap-hold-next-release trying to do an uppercase letter (ASDFLKJ) fails sometimes when typing fast.
I find out that this happens when the sequence is for example for an uppercase "A" instead of doing:

• press shift
• tap a
• release shift

that works with kmonad, I get the "A" from the key with the tap-hold-next-release binding.

However I do sometimes:

• press shift
• press a
• release shift
• release a

and that produces a "a" in lowercase. without kmonad running (or if I do that on other keys without the tap-hold-next-release) the uppercase letter is correctly produced.

This is the only reason I cannot use kmonad. I run into this issue so often that makes me feel triping on stones everything I am typing.