Enable Mouse Support in Tmux on OS X

Last revisited on , originally published on . Tmux OS X Workflow

Tmux is an integral part of my workflow. It automatically runs every time I start a new terminal. Unfortunately on OSX it’s not a perfect parent process for my shell: it doesn’t support scrolling through the scrollback using the mouse. To enable this we have to jump through some hoops.

Send Mouse Events through Terminal.app

We need to make Terminal.app send the mouse events through to the application running inside. If you’re using an advanced terminal such as iTerm, you can skip these steps because iTerm already supports mouse events.

  1. Install SIMBL1. Note that the installer is not signed, so you might have to open it from the context menu.
  2. Download MouseTerm or the more advanced MouseTerm Plus, and install2 it by running the Install file.
  3. Restart Terminal.app

Configure Tmux for Mouse Support

All that remains now is configuring Tmux to listen to the sent mouse events. In your .tmux.conf file add these lines:

set -g mode-mouse on
set -g mouse-resize-pane on
set -g mouse-select-pane on
set -g mouse-select-window on

Restart Tmux or run the Tmux command source ~/.tmux.conf, and you should be able to scroll up or down the scrollback with your mouse. You’ll also be able to select a pane with the mouse and resize them.

But scrolling still sucks

You might notice the scrolling is not as smooth like in the original Terminal.app – it jumps about 10 lines per tick of the mouse wheel. We’ll see how to fix that in my follow-up article Better mouse scrolling in Tmux.

  1. EasySIMBL is easier to install using brew cask install easysimbl. However as Wouter Martens noted in the comments below, it no longer works on OSX 10.10.4. Some say it will work again in 10.11 but for now we’re stuck with using SIMBL.

  2. If you’re using EasySIMBL, install by extracting the MouseTerm.bundle file and dragging it onto the EasySIMBL window.

David Verhasselt

Senior full-stack engineer with 5 years of experience building web applications for clients all over the world.

Interested in working together?

Find out what I can do for you or get in touch!

Like this? Sign up to get regular updates