tmux-drag

Reorder tmux windows by dragging their tabs in the status line, and swap tmux panes by dragging them in the pane area.

Windows are swapped as the pointer crosses their tabs. The active window does not change while dragging, so you can move a tab across several others and reverse direction before releasing it. A normal click still selects a window or pane.

Requirements

• tmux 3.2 or newer
• mouse enabled in tmux
• A terminal that sends mouse drag events

Installation

TPM

set -g @plugin 'rockofox/tmux-drag'

Press prefix + I to install it.

Manual

Load the entrypoint from your tmux configuration:

run-shell '/path/to/tmux-drag/tmux_drag.tmux'

The plugin adds mouse bindings and wraps the existing window status formats with tmux status ranges. It does not replace the status-line styling provided by another plugin.

Make sure mouse is enabled before loading the plugin:

set -g mouse on

Use

1. Press and hold the left mouse button on a window tab.
2. Move the pointer across the tabs you want to cross.
3. Release the button.

Each crossed tab swaps places with the dragged window. Window indexes and panes are left to tmux; the plugin only changes the order of existing windows.

To swap splits without interfering with normal terminal mouse behavior:

1. Hold Ctrl, then press and hold the left mouse button inside a pane.
2. Move the pointer into another pane, in the same window or another window.
3. Release the button.

Each crossed pane swaps places with the dragged pane. Pane sizes and layouts remain under tmux's control. Without Ctrl, tmux and the terminal retain their normal pane selection, text selection, and border resizing behavior.

Why use the plugin?

tmux can provide basic tab dragging with a binding such as the one discussed in tmux issue #656:

bind-key -n MouseDrag1Status swap-window -d -t=

This plugin uses the same tmux swap-window primitive, but adds a more complete drag interaction:

• Records the window where the drag started instead of relying on tmux's implicit current window.
• Swaps only when entering a new tab, avoiding repeated swaps while hovering over the same tab.
• Keeps the active window stable while dragging across multiple tabs.
• Selects the final tab when the mouse button is released.
• Preserves existing status-line styling while adding the ranges needed to identify tabs reliably.
• Installs the bindings and manages drag state automatically.

The one-line binding is still a good choice if you want the smallest possible configuration and basic drag-to-reorder behavior. This plugin is intended for predictable multi-tab drags without manual mouse-binding setup.

Development

Run the test suite from the repository root:

./tests/test.sh

The tests create a separate tmux server and socket, so they do not touch the tmux server used by your terminal.

Limitations

• Drag state is scoped to a session. Two clients dragging tabs or panes in the same session at the same time are not supported.
• Linked windows in other sessions are not reordered.
• Pane swaps across linked windows or sessions are not supported.
• Dragging a zoomed pane may still be handled by tmux as a zoom operation.
• Nested tmux sessions and terminals that do not forward drag events may interfere with mouse input.