# macOS Keyboard Shortcuts for tmux

It's easy to create custom macOS keyboard shortcuts with tmux key bindings using hex codes and Alacritty.

As a longtime macOS user, I am used to using the command key to get a lot done. You're probably familiar with `cmd+c` for copying to the clipboard, and `cmd+t` to create a new tab in Safari. Most power users agree that staying away from the mouse and keeping your hands on the keyboard for as long as possible will help you be faster and more efficient while working.

Unfortunately, tmux is a tool used in the terminal that doesn't leverage the command key at all, but rather all of it's commands are prefixed with the keystroke `ctrl+b` followed by a letter (ex: new window is `ctrl+b c`). I spent months building the muscle memory for the tmux keybindings, but it always felt slow compared to the macOS keyboard shortcuts.

So, using the [Alacritty terminal emulator](https://github.com/alacritty/alacritty), I found a way to customize tmux with my own macOS style keyboard shortcuts using the command key.

In this article, I'm going to show you how to create your own keyboard shortcut for tmux. We will go through the following steps:

1. Decide the keyboard shortcut
2. Get the hex code
3. Assign it to Alacritty

## 1. Decide the keyboard shortcut

Before you can assign the keyboard shortcut you have to decide what you want it to do. tmux uses a prefix (default: `control+b`) followed by a key to run a key binding. In macOS, keyboard shortcuts are driven by the command key plus an additional key.

As an example, you can create a new tmux window with `prefix+c`. tmux windows share the same UI pattern as tabs in macOS (ex: Safari tabs or Finder tabs). New tabs in macOS are created with the `cmd+t` keyboard shortcut.

So let's bind new tmux window to `cmd+t`.

## 2. Get the hex code

In order to simulate a keystroke, Alacritty uses hex codes, which is simply a combination of characters.

For our example, we need to get the hex code values for `<ctrl+b> c`. We will use `xxd` to record our keystrokes and dump the hex codes we need.

First run the following command (outside of tmux):

```sh
xxd -psd
```

Then type `ctrl+b`, `c`, then press the return key (aka `enter`). You will see the following data output in your terminal:

```
^Bc
02630a
```

Press `ctrl+c` to escape the xxd listener. You now have the hex code `02630a`, which stands for `ctrl+b c return`.

## 3. Assign it to Alacritty

Keystroke hex codes are bound to two character at a time. So from our code `02630a`, `02` stands for `ctrl+b`, `63` stands for `c`, and `0a` stands for `return`. Since we don't need the return key, we can drop it. Alacritty also wants us to escape each code with `\x{hex}` so the `chars` we want to use for `<prefix-b> c` will be `\x02\x63`.

Finally, we will use the `key` and `mods` keys to define the custom key binding. Add the following code to your `~/.config/alacritty/alacritty.yml` config file.

```yaml title="~/.config/alacritty/alacritty.yml"
key_bindings:
  - { key: T, mods: Command, chars: "\x02\x63" }
```

Now, while inside tmux, you can hit `cmd+t` to create a new window! The principles learned here can be applied to any key binding with any keystroke combination you can think of.

## Bonus: Additional Shortcuts

Here are some of the tmux keybindings I have set up with Alacritty to create more macOS like keyboard shortcuts:

```yaml title="~/.config/alacritty/alacritty.yml"
key_bindings:
  - { key: E, mods: Command, chars: "\x02\"" } # split tmux window vertically
  - { key: E, mods: Command|Shift, chars: "\x02%" } # split tmux window horizontally
  - { key: F, mods: Command, chars: "lfcd\n" } # open file manager 'gokcehan/lf'
  - { key: F, mods: Command|Shift, chars: "\x02\x5b\x2f" } # start tmux search mode
  - { key: G, mods: Command, chars: "\x02g" } # open git manager 'jesseduffield/lazygit'
  - { key: J, mods: Command, chars: "\x02\x54" } # open t - tmux smart session manager
  - { key: K, mods: Command, chars: "\x02s" } # open interactive tmux session client
  - { key: L, mods: Command, chars: "\x02L" } # switch to the last tmux session
  - { key: O, mods: Command, chars: "\x02u" } # open URLs 'joshmedeski/tmux-fzf-url'
  - { key: P, mods: Command, chars: ":GoToFile\n" } # files
  - { key: P, mods: Command|Shift, chars: ":GoToCommand\n" } # commands
  - { key: Q, mods: Command, chars: ":q\n" } # quit vim
  - { key: S, mods: Command, chars: "\x1b\x3a\x77\x0a" } # save vim buffer
  - { key: T, mods: Command, chars: "\x02c" } # create a new tmux window
  - { key: W, mods: Command, chars: "\x02x" } # kill the current pane
  - { key: Z, mods: Command, chars: "\x02z" } # toggle zoom state of the current tmux pane
  - { key: Tab, mods: Control, chars: "\x02n" } # switch to next tmux window
  - { key: Grave, mods: Control, chars: "\x02p" } # switch to previous tmux window
  - { key: Comma, mods: Command, chars: "\x02," } # rename the current tmux window
  - { key: LBracket, mods: Command, chars: "\x0f" } # navigate back in vim (ctrl+o)
  - { key: LBracket, mods: Command|Shift, chars: "\x02p" } # switch to next tmux window
  - { key: RBracket, mods: Command, chars: "\x09" } # navigate forward in vim (ctrl+i)
  - { key: RBracket, mods: Command|Shift, chars: "\x02n" } # switch to previous tmux window
  - { key: Semicolon, mods: Command, chars: "\x02:" } # enter the tmux command prompt
  - { key: Key1, mods: Command, chars: "\x021" } # select tmux window 1
  - { key: Key2, mods: Command, chars: "\x022" } #                ... 2
  - { key: Key3, mods: Command, chars: "\x023" } #                ... 3
  - { key: Key4, mods: Command, chars: "\x024" } #                ... 4
  - { key: Key5, mods: Command, chars: "\x025" } #                ... 5
  - { key: Key6, mods: Command, chars: "\x026" } #                ... 6
  - { key: Key7, mods: Command, chars: "\x027" } #                ... 7
  - { key: Key8, mods: Command, chars: "\x028" } #                ... 8
  - { key: Key9, mods: Command, chars: "\x029" } #                ... 9
```

To see my latest keybindings, check out my full [`alacritty.yml` file on GitHub](https://github.com/joshmedeski/dotfiles/blob/main/.config/alacritty/alacritty.yml)