The Modes of tmux
Tags: tmux, todayilearned, terminal
Published: 2021-01-03 06:05:15

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](https://twitter.com/jbrancha/status/1339265925418258434?s=20), 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](https://crafty-builder-6996.ck.page/e169c61186
) to get a direct line on more stuff like this._

---

<em>Cover photo by <a href="https://unsplash.com/@david_watkis?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">David Watkis</a> on <a href="/s/photos/traffic-light?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>
  </em>