macOS Keyboard Shortcuts for tmux

Josh MedeskiFri, Jul 16th, 20215 minstechnology, productivity

As a longtime macOS user, I am used to using the command key to get a lot done. You're probably familar 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, 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):

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.

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:

key_bindings:
  # Rename the current tmux window
  - { key: Comma, mods: Command, chars: "\x02\x2c" }
  # Select a new tmux session for the attached client interactively
  - { key: K, mods: Command, chars: "\x02\x73" }
  # Select window 1-9
  - { key: Key1, mods: Command, chars: "\x02\x31" }
  - { key: Key2, mods: Command, chars: "\x02\x32" }
  - { key: Key3, mods: Command, chars: "\x02\x33" }
  - { key: Key4, mods: Command, chars: "\x02\x34" }
  - { key: Key5, mods: Command, chars: "\x02\x35" }
  - { key: Key6, mods: Command, chars: "\x02\x36" }
  - { key: Key7, mods: Command, chars: "\x02\x37" }
  - { key: Key8, mods: Command, chars: "\x02\x38" }
  - { key: Key9, mods: Command, chars: "\x02\x39" }
  # Switch to last tmux session
  - { key: L, mods: Command, chars: "\x02\x4c" }
  - { key: LBracket, mods: Command, chars: "\x02\x5b" }
  # Change to the previous tmux window
  - { key: LBracket, mods: Command|Shift, chars: "\x02\x70" }
  # Split the current pane into two, left and right
  - { key: N, mods: Command|Shift, chars: "\x02\x25" }
  # Split the current pane into two, top and bottom.
  - { key: N, mods: Command, chars: "\x02\x22" }
  # Detach the current tmux client
  - { key: Q, mods: Command, chars: "\x02\x64" }
  # Change to the next tmux window
  - { key: RBracket, mods: Command|Shift, chars: "\x02\x6e" }
  # Type <escape>:w<enter> to save neovim
  - { key: S, mods: Command, chars: "\x1b\x3a\x77\x0a" }
  # Create a new tmux window
  - { key: T, mods: Command, chars: "\x02\x63" }
  # Break the current tmux pane out of the tmux window
  - { key: T, mods: Command|Shift, chars: "\x02\x21" }
  # Kill the current tmux pane (and window if last pane)
  - { key: W, mods: Command, chars: "\x02\x78" }
  # Toggle the zoom state of the current tmux pane
  - { key: Z, mods: Command, chars: "\x02\x7a" }

Sign up for my newsletter

Get the latest blog posts and updates strait to your inbox.