tmux mouse mode in macOS

Text selection with mouse in tmux

Excellent! I’m finally making further improvements to my tmux setup.

Namely, I’m sorting out mouse mode in tmux - in both macOS and Linux.

Why would you need a mouse in tmux?

It’s a valid question, and truth is you technically don’t. tmux is one of these truly console-native tools that have full support for getting everything done with just a keyboard.

For instance, I’m already scrolling tmux buffers and search them by text - all from keyboard. I know how to scroll text buffers and really like the shortcuts available for it.

But reality is that terminal is only one of the tools I use for getting my daily tasks accomplished. And quite often I need to be switching to other apps for taking notes or copy-pasting certain parameters from Wikis and spreadsheets. So I can’t help but use mouse with those tools, and this means I often attempt using mouse back in console as well.

Most annoying thing for me in this regard is when I attempt to scroll screen history in terminal - expectation is I see previous lines of text output in the console, but with tmux these lines are in tmux buffer, not in the terminal app’s one. So scrolling results in getting empty lines or some random information.

Second most annoying thing is selecting text in tmux panes! I quite often split one of tmux windows into two vertical panes, and because each is a separate session you get used to working with them very quickly. But when you need to select a bit of text from one of the panes to copy, doing it with mouse by default selects text across both panes. This happens because mouse selection is not aware of tmux panes - so it treats the whole terminal app window as one text to be working with: Caption

Enabling mouse mote in tmux

You need to add the following into your .tmux.conf file:

# mouse support
set -g mouse on

Benefits of mouse mode in tmux

Text Buffer History

This immediately feels much natural! You mouse scroll in a terminal app window and instead of random results you get exactly the content expected - previous lines that were shown in your session. A true added benefit is knowing that this text is actually in tmux buffer, so you can scroll and search it using native tmux methods.

As usual, current line is reported along with total number of linex in tmux pane buffer in the top rigth (numbers in yeallow): Scrolling with mouse in tmux

Selection in tmux panes

Selecting text in a tmux pane

tmux clipboard vs system clipboard

This was one of the things that kept me from adopting mouse mode sooner: tmux copies selected text into its own buffer, not the system clipboard. Before you have any mouse mode enabled, it seems to work quite well - whatever you select with mouse is copied into system clipboard, everything else happens in tmux buffers.

But once mouse mode is enabled, things get confusing: suddenly no mouse selected text is available in system clipboard. So in order for this to work, you need to make tmux copy function use a command-line utility for copying selected text into system clipboard - in macOS it’s pbcopy command.

There’s a bit of a learning curve here, but basic approach I chose for myself is:

• quick double-click selections must copy selected text into both tmux and system clipboards This super simple behavior is configured using a rather complex code:

bind-key -n DoubleClick1Pane \
    select-pane \; \
    copy-mode -M \; \
    send-keys -X select-word \; \
    run-shell "sleep .5s" \; \
    send-keys -X copy-selection-and-cancel\; run "tmux save-buffer - | pbcopy"

I have taken this example form a StackOverflow thread on double-cllick copy in tmux.

• more complex multi-line selections go into tmux buffer by default, but can go to system buffer if you press Enter to kind of “commit” the selection into system buffer.

Here’s how to configure tmux to copy selection into system clipboard using pbcopy command:

unbind -Tcopy-mode-vi Enter
bind -Tcopy-mode-vi Enter send -X copy-selection-and-cancel\; run "tmux save-buffer - | pbcopy"

See Also

• pbcopy command
• macOS commands
• macOS