tmux
June 11, 2020 — November 20, 2024
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 the 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
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.
- 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 mean time, I am be 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
orPgDn
) to scroll around. Pressq
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 usingShift
+k
andShift
+j
(if you’re already in scroll mode). WithoutShift
, 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
orC-e
C-Down
Scroll up C-Up
orC-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 sinceC-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
:
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:
- brennanfee/tmux-paste: Tmux plugin for pasting from system clipboard. Works on macOS, Linux, Cygwin, and WSL (Windows Subsystem For Linux). Here is a configuration that laboriously restores normalcy: Copy and Paste in tmux.
- tmux-plugins/tmux-yank: Tmux plugin for copying to system clipboard. Works on OSX, Linux and Cygwin.
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 additional require the keybinding.
The last is from a length perplexity chat that doesn’t makes 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.
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
?