#+TITLE: karabiner-config
#+AUTHOR: Pedro Delfino
#+OPTIONS: toc:nil num:nil

[[file:painting.jpg]]

/"Delivery of the Keys" (1481-1482) by Pietro Perugino -- [[https://en.wikipedia.org/wiki/Delivery_of_the_Keys_(Perugino)][Wikipedia]]/

*Turning macOS into a well-behaved Emacs citizen.*

A custom [[https://karabiner-elements.pqrs.org/][Karabiner Elements]] configuration that brings Emacs-style keybindings system-wide on macOS and provides single-keystroke application launchers. If your fingers already think in =C-f=, =C-n=, and =C-x C-s=, this config makes the rest of your OS speak the same language.

* Profiles

Three profiles optimized for different keyboards:

| Profile          | Keyboard                  |
|------------------+---------------------------|
| =mac-default=    | Built-in MacBook keyboard |
| =logi-ergonomic= | Logitech Ergo K860        |
| =glove80=        | MoErgo Glove80 split keyboard |

* Features

** Application Launchers

Launch apps instantly with =Right Option= + key:

| Shortcut             | Application                              |
|----------------------+------------------------------------------|
| =Right Option + f=   | Emacs                                    |
| =Right Option + a=   | iTerm2                                   |
| =Right Option + d=   | Brave Browser                            |
| =Right Option + s=   | Google Chrome (automated test instance)  |
| =Right Option + w=   | Balance (localhost:3005)                 |
| =Right Option + c=   | Signal                                   |
| =Right Option + x=   | Messages                                 |
| =Right Option + v=   | Telegram Desktop                         |
| =Right Option + t=   | VLC Player                               |
| =Right Option + g=   | Preview                                  |

** Screenshots for Claude Code
| Shortcut             | Action                                                        |
|----------------------+---------------------------------------------------------------|
| =Right Option + r=   | Region screenshot straight to the clipboard (no file)         |
| =Right Option + e=   | Shottr captures the active window, no mouse; =Esc= copies it   |

Emits macOS =Cmd+Ctrl+Shift+4=. Drag a region, then paste into Claude
Code with =Ctrl+V= (or =Cmd+V= in iTerm2 with "Save to Temp File and
Paste Path" remembered). For arrows, boxes or a scrolling capture use
Shottr instead (=Cmd+Shift+2=, =Esc= copies).

** Emacs Keybindings

Comprehensive Emacs keybindings that work across all macOS applications. Emacs and Terminal are excluded so their native bindings are preserved.

*** Navigation

| Shortcut | Action                |
|----------+-----------------------|
| =C-f=    | Forward character     |
| =C-b=    | Backward character    |
| =C-n=    | Next line             |
| =C-p=    | Previous line         |
| =C-a=    | Beginning of line     |
| =C-e=    | End of line           |
| =M-f=    | Forward word          |
| =M-b=    | Backward word         |
| =C-v=    | Page down             |
| =M-v=    | Page up               |
| =M-<=    | Beginning of document |
| =M->=    | End of document       |

*** Editing

| Shortcut | Action              |
|----------+---------------------|
| =C-d=    | Delete forward      |
| =C-h=    | Delete backward     |
| =C-k=    | Kill line           |
| =M-d=    | Delete word forward |
| =C-w=    | Cut                 |
| =M-w=    | Copy                |
| =C-y=    | Paste               |
| =C-/=    | Undo                |

*** C-x Prefix Commands

| Shortcut  | Action           |
|-----------+------------------|
| =C-x C-s= | Save             |
| =C-x C-f= | Open file        |
| =C-x C-c= | Quit application |
| =C-x k=   | Close tab        |
| =C-x h=   | Select all       |
| =C-x u=   | Undo             |

*** Clipboard Integration

=M-y= is remapped to =Ctrl+Option+Cmd+Y= outside Emacs to trigger [[https://maccy.app/][Maccy]] (clipboard manager). Inside Emacs, =M-y= passes through untouched and triggers =counsel-yank-pop= as usual. Both share the system clipboard, so the kill ring and Maccy stay in sync.

*** Control Key Emulations

| Shortcut | Action          |
|----------+-----------------|
| =C-i=    | Tab             |
| =C-m=    | Return / Enter  |
| =C-[=    | Escape          |
| =C-]=    | Escape          |

*** Other Shortcuts

| Shortcut | Action                     |
|----------+----------------------------|
| =C-g=    | Escape / Cancel            |
| =C-s=    | Search (in supported apps) |
| =C-t=    | New tab                    |
| =C-l=    | Focus URL bar (browsers)   |
| =C-z=    | Undo                       |

* Design Principles

- *Home row focused* -- minimize finger travel
- *Touch typing friendly* -- leverage muscle memory
- *Emacs everywhere* -- consistent keybindings across macOS
- *Keyboard agnostic* -- works with built-in, external, and split keyboards

* Installation

1. Install [[https://karabiner-elements.pqrs.org/][Karabiner Elements]]
2. Clone this repository
3. Symlink or copy =karabiner.json= to =~/.config/karabiner/karabiner.json=:

#+begin_src bash
ln -sf $(pwd)/karabiner.json ~/.config/karabiner/karabiner.json
#+end_src

* Related

- [[https://github.com/pdelfino/emacs-config][emacs-config]] -- The Emacs setup these keybindings complement
- [[https://github.com/pdelfino/homerow-config][homerow-config]] -- Click things without a mouse
- [[https://github.com/pdelfino/my-shortkeys-config][my-shortkeys-config]] -- Emacs-style shortcuts in the browser
- [[https://github.com/pdelfino/claude-config][claude-config]] -- Claude Code configuration
- [[https://github.com/pdelfino/iterm2-config][iterm2-config]] -- iTerm2 terminal profile
- [[https://github.com/pdelfino/zshrc][zshrc]] -- Shell configuration with Emacs keybindings
- [[https://github.com/pdelfino/macos-setup][macos-setup]] -- The bootstrap that ties it all together

* License

MIT