Selective Mouse Support in tmux: When to Use Granular Options vs the Global Switch

Decision and Constraints

You want to enable mouse‑based pane selection and resizing in tmux, but clicking the status bar should not accidentally switch windows. The configuration must work with tmux ≥ 1.8 (for granular options) or ≥ 2.1 (for the unified mouse option) and must not break terminal applications that rely on mouse reporting such as vim, less, or grep.

Supported Mouse Options

Option	tmux version	Effect	Notes
set -g mouse on	≥ 2.1	Enables pane select, resize, and window select	Simplest but may cause unwanted window switches when clicking the status bar
set -g mouse-select-pane on; set -g mouse-resize-pane on	≥ 1.8	Enables pane select and resize only	Granular control, compatible with older releases; deprecated in tmux ≥ 2.1
set -g mouse-select-pane off; set -g mouse-resize-pane off; set -g mouse-select-window off	any	Disables all mouse interactions	Prevents interference but loses convenience

Trade‑offs

• Global mouse option (mouse on) reduces config complexity but can trigger window changes when you click the status bar or window list.
• Selective options avoid unintended window switches and work on older tmux versions, but require two separate lines and are ignored if the global mouse option is also set.
• Disabling mouse eliminates any interference but forces keyboard‑only navigation, which may be less convenient for quick pane resizing.

Implementation

1. Open your user tmux configuration file (usually ~/.tmux.conf) in a text editor. You need read/write permission to your home directory; no elevated privileges are required.
2. Add the selective lines:

   # Enable mouse pane selection and resizing only
   set -g mouse-select-pane on
   set -g mouse-resize-pane on
   

3. Save the file.
4. Reload the configuration in a running tmux server:

   tmux source-file ~/.tmux.conf
   

   Alternatively, start a new tmux session to pick up the changes.
5. Verify that the options are active:

tmux show-options -g mouse-select-pane mouse-resize-pane

Both should return on. If you see off or an error, check that no global mouse on line is present later in the file.

Validation

1. Enter a tmux session (e.g., tmux new -s test).
2. Click inside a pane; the pane should gain focus without changing the current window.
3. Click and drag a pane border; the pane should resize smoothly.
4. Click the tmux status bar or window list; the current window should remain unchanged.

Successful completion of these steps confirms that mouse pane selection and resizing work as intended while window selection stays disabled.

Limitations and Practical Checks

• The selective mouse options are ignored if a later set -g mouse on appears in the configuration. Ensure only one method is used.
• Some terminal emulators forward mouse events to applications before tmux sees them. If you notice unexpected behavior in vim or less, consider adding set -g focus-events on to let applications handle mouse events directly, or temporarily disable the selective options to isolate the issue.
• To confirm that mouse reporting is not interfering with applications, run a test inside tmux: vim and try to select text with the mouse; the selection should behave as it would outside tmux.
• You can always re‑check the active options with tmux show-options -g mouse-select-pane mouse-resize-pane after any config change.