The Modes of tmux

tmux is a tool that is so ingrained in my setup and workflow, that I almost forget it is there. Because of that, I use it in very specific ways and tend not to learn other features or ways of doing things.

As I've rebuilt my tmux config from scratch, I've learned a bunch of new things. One of those things in particular stands out.

tmux is modal.

What does it mean that it is modal?

That means that tmux has different modes that it operates in. There are certain features, capabilities, and keybindings associated with each mode. Work will happen in one mode, then when you need to do something unique to one of the other modes, you switch to that other mode. When you're done, or as the result of completing an action, you'll switch back to the original mode. This is what it means for a tool to be modal (Vim is another, perhaps more notably modal tool).

tmux has four (five really, but I won't get into command mode) modes that I tend to operate in as I use it day to day. The primary mode (which doesn't have a name from what I can tell) is the mode I'm in 99% of the time. Because of that and because it is essentially a window through which I'm viewing the terminal, it tends to feel invisible.

From this primary mode, I can switch to three other modes.

1. Copy Mode
2. View Mode
3. Choose Mode

Let's look at each of these in turn.

Copy Mode

Copy mode allows me to navigate to anywhere in the history of the current pane, make a selection, and copy that to the paste buffer.

Copy mode can be switched to by hitting <Prefix [. From here, depending on which key-mode is configured, I can navigate around, search, make a visual selection, and then copy that to the tmux paste buffer. Copying a selection or hitting enter will return me to the primary mode.

View Mode

View mode is similar to Copy Mode, but is the result of a keybinding that produces output, such as list key bindings (<Prefix> ?).

Another example of view mode is list-keys (activated by executing <Prefix>:list-keys) which shows all the keybindings that are set up for this context (session, window, pane). Hitting enter will return me to the primary mode.

Choose Mode

Choose mode displays a list of options and allows me to choose one of those options. choose-buffers is a great example of this, allowing me to browse and select from tmux's copy buffer history.

<Prefix> s (choose a session) and <Prefix> w (choose a window) are other examples of bindings that put me into choose mode. After making a selection from one of these, I'll be switched to the particular session or window and placed back in the primary mode.

Custom Keybindings

When adding custom keybindings to your tmux config that are meant to work in copy-mode, you'll need to specify the binding's key table as copy-mode.

bind-key -T copy-mode 0 send-keys -X start-of-line

You can look up copy-mode (and copy-mode-vi) bindings with the list-keys command:

$ tmux list-keys -T copy-mode

Conclusion

You'll spend most of your time in the primary mode, but it's invaluable to have an understanding of the other modes and how you get there. Knowing your tool will allow you to make the most of it.

If you enjoyed this post, join my newsletter to get a direct line on more stuff like this.

Cover photo by David Watkis on Unsplash