tmux

June 11, 2020 — December 19, 2024

computers are awful
faster pussycat
plain text
POSIX
Figure 1

tmux is functionally a baffling but useful terminal session manager.

If you were following along in that terminal-session-management-from-base-principles notebook, you can think of it as something like the union of abduco and dvtm into a single app. It is a modern version of the ancient GNU screen with a more modern feature set and fewer oddities, which is saying a lot about how many oddities screen had.

On one hand, it is easy because it is so popular and thus documented everywhere, and installed most places. On the other, it is confusing and has weird terminology, so I need all that documentation to work out what I just did.

Here are some intros to tmux: 0 1, 2 and a cheat sheet.

1 World’s shortest introduction

terminology note

tmux creates “sessions” which seem to be connections to a host, which contain “windows”, which are virtual terminals within that session. Both these persist if you log in or out.

tmux ls  # list sessions
tmux new -s mysession  # create a new session
tmux attach -t mysession  # resume a session
Create new windows (which are virtual terminals)
Ctrl-b c
Previous/next window
Ctrl-b p/C-b n

Now, read on for more practicalities.

2 Scrolling, mousing

The tmux keyboard shortcuts are different to all the other shortcuts for reasons that are not clear to me. This is irritating when scrolling and copying text. Also, using the mouse, even touching the scroll wheel, does weird things.

This seems to be based around some design aesthetic wherein tmux has to do things its own way. Rather than having Ctrl-V paste, or anything so unsophisticated as that, instead copying and pasting are implemented with various “modes”, each of which has an elaborate maze of keyboard shortcuts which can notionally do even more subtle variations upon copy and pasting than you are used to. This is probably amazing if you are prepared to spend a few hours learning how to do it. In the meantime, I am unable to copy and paste anything at all. Workarounds follow.

2.1 Scrolling AHHHHH!

There are various keyboard shortcuts. They are a shambles in jarring conflict with my muscle memory from non-tmux life.

Ctrl + b then [ to enter scroll mode, then use your normal navigation keys (e.g., Up Arrow or PgDn) to scroll around. Press q to quit scroll mode.

Alternatively, press Ctrl + b + PgUp to directly enter copy mode and scroll one page up (useful for most cases).

In vi mode (see below), you can scroll the page up/down line by line using Shift + k and Shift + j (if you’re already in scroll mode). Without Shift, the cursor moves instead of the page.

Excerpts from the tmux man page:

tmux may be controlled from an attached client by using a key combination of a prefix key, C-b (Ctrl-b) by default, followed by a command key.

Default Command Key Bindings:

Function vi emacs
Half page down C-d M-Down
Half page up C-u M-Up
Next page C-f Page down
Previous page C-b Page up
Scroll down C-Down or C-e C-Down
Scroll up C-Up or C-y C-Up
Search again n n
Search again in reverse N N
Search backward ? C-r
Search forward / C-s

Note: You have to press C-b twice if you use that for page up since C-b is bound as the command key. See the man page for information on prefacing a copy mode command with a repeat count.

Got all that?

2.2 Mouse scrolling

Mouse scrolling is enabled by mouse mode. This is enabled by adding the following to ~/.tmux.conf:

set -g set-clipboard on
set -g mouse on

Ctrl-b: source-file ~/.tmux.conf will reload the configuration file if we are doing this in a live tmux session.

Mouse mode is still not ideal IMO, in that it does not simply seamlessly make the mouse do what the mouse usually does; that would be too easy.

Instead, it tries to be way too clever, too clever at least for my tastes. Sometimes it scrolls back through command history, which is downright evil. Why would I want this app, alone of all in the universe, to do such a thing? When do I want my search back through something so precise as system commands to be a kinetic slalom? The kind of person who wants this performs surgery with a chainsaw. I just want this thing to do its best to pretend to be a normal terminal and not try to throw unsolicited clever tricks at me while I’m concentrating. All tips on killing that with fire gratefully accepted.

When the scrolling is doing what I want and scrolling the window content, it is still not as smooth as in a normal terminal; I regularly find myself trying to make infinitesimal finger movements in order to scroll ordinary amounts, and then overshooting. Still if you like careening through hundreds of pages of content quasi-randomly, this is the feature for you.

2.3 Oh no now copy/paste is broken

You would like to copy stuff from terminal? tl;dr shift clicking probably does what you want.

long version: There are an annoying number of different things that can break in tmux. Mouse mode breaks copy-paste in that it per-default only copies into a tmux internal buffer, not into the global clipboard. This is different to the previous macOS-specific problem..

I am sure this feature suits someone out there (Hello that one guy!), but not me, because I also use non-terminal apps. The workarounds listed at that link do not seem to work on remote terminals.

Possibly installing plugins helps, e.g. these two seem to work together to fix the problem:

This is quite tedious to set up. In fact, I find it easier to take a screenshot of my terminal and then run OCR on it.

In macOS with vscode the setting integrated.macOptionClickForcesSelection: true allows us to select text in the terminal using option+click when selecting text. We probably additionally require the keybinding.

{
  "key": "cmd+v",
  "command": "workbench.action.terminal.paste",
  "when": "terminalFocus"
}

The last is from a length perplexity chat that doesn’t make the attribution clear.

2.4 Now quitting tmux causes pain

If the mouse scroll mode causes things to break after quitting tmux, and clicking on the window causes this kind of crap to appear: 0;38;15M 0;38;15m 0;60;12M0;60;12m0;56;14M0;56;14m0;56;14M0;56;14m0;54;13M0;54;13m0;54;13M0;54;13m… eek, yes me too! Running reset puts things right in some circumstances. Other times (e.g. in hyper) reloading the terminal from the app window is necessary (Ctrl-Shift-R).

3 Ecosystem

There are various other tools in the ecosystem, e.g. tmuxinator is a config tool for tmux.

3.1 tmux-plugins

tmux-plugins, mentioned above in the context of tmux-paste and tmux-yank

3.2 Integration with virtual terminal

A neat feature of tmux is that it has a magical integration with iterm2 on macOS, which is known as “control centre” mode. This makes usage more intuitive by recycling the terminal GUI for handling session management. However, integration is controversial and does not seem supported widely across other terminal emulators.

3.3 Byobu

Byobu is a GPLv3 open source text-based window manager and terminal multiplexer.… Byobu now includes enhanced profiles, convenient keybindings, configuration utilities, and toggle-able system status notifications for both the GNU Screen window manager and the more modern Tmux terminal multiplexer, and works on most Linux, BSD, and Mac distributions.

Dirk Eddelebuttel points out

byobu uses (by default) one socket you can designate a particular socket and share ‘write’ permission with another users and BAM you have multi-session multi-user work for any application that can run a terminal

Question: since tmux can already work over named sockets, can tmux do this without special treatment from byobu?