tmux

2020-06-11 — 2025-10-15

Wherein terminal sessions are managed and are persisted across logins; mouse-driven scrolling and clipboard handling are treated as separate behaviors, and plugins together with iTerm2 integration are noted.

computers are awful
faster pussycat
plain text
POSIX
Figure 1

tmux is a baffling yet functional terminal session manager. On the one hand, it’s easy — it’s so popular, documented everywhere, and installed in most places.

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

If you were following along in that terminal-session-management-from-base-principles notebook, you can think of tmux as something like the union of abduco and dvtm into a single app, or a competitor to Zellij. It is more modern than the ancient GNU screen with greater extensibility and fewer oddities; this is saying more about how many oddities screen had than about how few tmux has.

1 World’s shortest introduction

Noteterminology 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 from other shortcuts, for reasons that aren’t clear to me. That’s irritating when we scroll and copy text. Also, using the mouse — even touching the scroll wheel — does weird things.

This seems driven by a design aesthetic in which tmux does things its own way. Rather than just having Ctrl-V paste, copying and pasting are implemented with various “modes”, each with an elaborate maze of keyboard shortcuts that can, in principle, produce subtler variations on copying and pasting than we’re used to. This is probably amazing if we’re prepared to spend a few hours learning it. In the meantime, I can’t copy or 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

We enable mouse scrolling via mouse mode. Add 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’re doing this in a live tmux session.

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

Instead, it tries to be way too clever, at least for my tastes. Sometimes it scrolls back through command history, and that’s downright evil. Why would I want this app, of all apps in the universe, to do that? When would I want my search through something as precise as system commands to be a kinetic slalom? The kind of person who wants this performs surgery with a chainsaw. I just want it to behave like 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’s still not as smooth as in a normal terminal; I regularly try to make infinitesimal finger movements to scroll ordinary amounts, then overshoot. 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

Want to copy stuff from the terminal? tl;dr Shift-clicking probably does what we want.

Long version:There are an annoying number of different things that can break in tmux. Mouse mode breaks copy-paste because by default it only copies into a tmux internal buffer, not into the global clipboard. There is also a macOS-specific problem that [TODO clarify]

I’m sure this feature suits someone out there (hello that one guy!), but not me, since I also use non-terminal apps. The workarounds listed on that page don’t seem to work on remote terminals.

Installing plugins might help; for example, these two seem to work together to fix the problem:

It’s quite tedious to set up. Actually, I find it easier to take a screenshot of my terminal and run OCR on it.

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

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

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

To use a remote terminal from the command line, we need osc52.

# ~/.tmux.conf (remote)
set -g set-clipboard on
set -as terminal-overrides ',*:Ms=\E]52;c;%p1%s\x07'

2.4 Now quitting tmux causes pain

If the mouse scroll mode causes things to break after quitting tmux, and clicking the window makes this kind of crap 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 fixes things in some cases. Other times — for example, in hyper — we need to reload the terminal from the app window (Ctrl-Shift-R).

3 Ecosystem

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

3.1 AI

TmuxAI is an intelligent terminal assistant that lives inside your tmux sessions. Unlike other CLI AI tools, TmuxAI observes and understands the content of your tmux panes, providing assistance without requiring you to change your workflow or interrupt your terminal sessions.

Think of TmuxAI as a pair programmer that sits beside you, watching your terminal environment exactly as you see it. It can understand what you’re working on across multiple panes, help solve problems and execute commands on your behalf in a dedicated execution pane.

[…] TmuxAI’s design philosophy mirrors the way humans collaborate at the terminal. Just as a colleague sitting next to you would observe your screen, understand context from what’s visible, and help accordingly, TmuxAI:

  1. Observes: Reads the visible content in all your panes
  2. Communicates: Uses a dedicated chat pane for interaction
  3. Acts: Can execute commands in a separate execution pane (with your permission)

This approach provides powerful AI assistance while respecting your existing workflow and maintaining the familiar terminal environment you’re already comfortable with.

3.2 tmux-plugins

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

3.3 Integration with virtual terminal

A neat feature of tmux is a magical integration with iTerm2 on macOS, known as “control centre” mode. This makes it more intuitive to use by reusing the terminal GUI to handle session management. However, that integration is controversial and doesn’t seem to be widely supported across other terminal emulators.

3.4 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 we do this without special treatment from byobu?

4 Incoming