Home

Awesome

tmux-modal

Execute complex tmux commands in just a few keystrokes. tmux-modal introduces a modal mode (e.g. like in Vim text editor) in tmux that is designed to be efficient, easy to remember and comfortable.

Examples

Hit M-m (Alt-m in tmux terminology) first to enter the modal command mode. The status bar will show [=] to indicate that we are now in the modal mode (hit M-m again to exit back to "normal" mode). Here are some quick examples what one can do with tmux-modal (see the keybindings for a complete list).

Navigation

Easily move between panes and windows:

navigation-demo

Management

Create and delete windows with a breeze. Split, delete, zoom, move and break panes and much more in just a few keystrokes:

management-gif

Sticky commands

Use sticky commands to do more, repeatedly. Sticky commands enters a specific modal mode with specialized keybindings (see keybindings for a more detailed explanation and a full list of available commands).

sticky-window-gif

Hit w w to enter sticky window command:

Hit w r to enter sticky resize window command:

sticky-resize-gif

Install

Tmux Plugin Manager

Using Tmux Plugin Manager is the recommended way to install tmux-modal. Just add it as a plugin in your ~/.tmux.conf:

set -g @plugin 'whame/tmux-modal'

Then hit prefix + I to install it (see the documentaion for Tmux Plugin Manager for more details).

Manually

You can also clone and manually install tmux-modal. Put this at the end of your ~/.tmux.conf:

run /path/to/cloned/tmux-modal/tmux-modal.tmux

Note however that in this case you have to manually sync the cloned repository in order to get bug fixes, new features etc.

Keybindings

The following are the default keybindings of tmux-modal. (Note that these are customizable, as well as the command executed for each! See option @modal-keybindings-conf and @modal-commands-conf, respectively.)

Main

KeybindingDescriptiontmux Command
M-mEnter modal command mode.-
M-mExit modal command mode.-
yPaste buffer (e.g. from copy mode).paste-buffer
cEnter copy-mode.copy-mode
qQuit sticky command.-
:Open tmux command mode.command-prompt

Window

KeybindingDescriptiontmux Command
w wEnter sticky window command mode.-
w 0Go to window 0. This is an alias for g w 0.select-window -t :0
w 1Go to window 1. This is an alias for g w 1.select-window -t :1
w 2Go to window 2. This is an alias for g w 2.select-window -t :2
w 3Go to window 3. This is an alias for g w 3.select-window -t :3
w 4Go to window 4. This is an alias for g w 4.select-window -t :4
w 5Go to window 5. This is an alias for g w 5.select-window -t :5
w 6Go to window 6. This is an alias for g w 6.select-window -t :6
w 7Go to window 7. This is an alias for g w 7.select-window -t :7
w 8Go to window 8. This is an alias for g w 8.select-window -t :8
w 9Go to window 9. This is an alias for g w 9.select-window -t :9
w tSelect window with tree view. This is an alias for g w t.choose-tree -Zw
w iSelect window with index. This is an alias for g w i.command-prompt -p index "select-window -t ':%%'"
w hSelect left pane.select-pane -L
w lSelect right pane.select-pane -R
w kSelect above pane.select-pane -U
w jSelect below pane.select-pane -D
w dDelete window pane.kill-pane
w HSelect previous window. This is an alias for g w h.select-window -t :-
w LSelect next window. This is an alias for g w l.select-window -t :+
w DDelete window.kill-window
w cCreate new window.new-window
w oSelect other/last window.last-window
w zZoom pane.resize-pane -Z
w bBreak pane into a new window.break-pane
w nDisplay pane numbers.display-panes
w ,Rename window.command-prompt -I "#W" "rename-window -- '%%'"
w s lSplit window pane right.split-window -h
w s jSplit window pane down.split-window
w m kMove window pane up.swap-pane -U
w m jMove window pane down.swap-pane -D
w a 1Arrange window to layout 1.select-layout even-horizontal
w a 2Arrange window to layout 2.select-layout even-vertical
w a 3Arrange window to layout 3.select-layout main-horizontal
w a 4Arrange window to layout 4.select-layout main-vertical

Note that the sticky window command (w w) allows one to execute all of the above commands in the table but without the initial w. For example, after hitting w w, s l splits the window pane to the right, d deletes the window pane, h selects the left pane and so on (q exits the sticky command). Also see the option @modal-always-sticky if you instead always want to use the sticky command version (with only hitting w once).

Resize

KeybindingDescriptiontmux Command
w rEnter sticky resize window command-

When in sticky resize window command, the following resizes the window (as usual, q exits the sticky command).

KeybindingDescriptiontmux Command
hResizes the window pane one step to the left.resize-pane -L
lResizes the window pane one step to the right.resize-pane -R
jResizes the window pane one step downwards.resize-pane -D
kResizes the window pane one step upwards.resize-pane -U
HResizes the window pane multiple steps to the left.resize-pane -L 5
LResizes the window pane multiple steps to the right.resize-pane -R 5
JResizes the window pane multiple steps downwards.resize-pane -D 5
KResizes the window pane multiple steps upwards.resize-pane -U 5

Session

KeybindingDescriptiontmux Command
s dDetach session.detach-client
s hSelect previous session. This is an alias for g s h.switch-client -p
s lSelect next session. This is an alias for g s l.switch-client -n
s tSelect session with tree view. This is an alias for g s t.choose-tree -Zs
s DDelete session.kill-session
s ,Rename session.command-prompt -I "#S" "rename-session '%%'"

Go to

Window

KeybindingDescriptiontmux Command
g w 0Go to window 0.select-window -t :0
g w 1Go to window 1.select-window -t :1
g w 2Go to window 2.select-window -t :2
g w 3Go to window 3.select-window -t :3
g w 4Go to window 4.select-window -t :4
g w 5Go to window 5.select-window -t :5
g w 6Go to window 6.select-window -t :6
g w 7Go to window 7.select-window -t :7
g w 8Go to window 8.select-window -t :8
g w 9Go to window 9.select-window -t :9
g w tGo to window with tree view.choose-tree -Zw
g w iGo to window with index.command-prompt -p index "select-window -t ':%%'"
g w hGo to previous window.select-window -t :-
g w lGo to next window.select-window -t :+
g w oGo to other/last window.last-window

Session

KeybindingDescriptiontmux Command
g s hGo to previous session.switch-client -p
g s lGo to next session.switch-client -n
g s tGo to session with tree view.choose-tree -Zs

Customization

Custom keybindings

The option @modal-keybindings-conf can be set to load custom keybindings. The file keybindings.conf shows the default keybindings and can be used as a template. Thus, copy the file and modify it to your liking, and finally set this in your .tmux.conf to load them:

set -g @modal-keybindings-conf /path/to/my-tmux-modal-keybindings.conf

Custom commands

The option @modal-commands-conf can be set to load custom commands that will be executed for the keybindings. The file commands.conf shows the default commands and can be used as a template. Thus, copy the file and modify it to your liking, and finally set this in your .tmux.conf to load them:

set -g @modal-commands-conf /path/to/my-tmux-modal-commands.conf

Start with modal command mode

The option @modal-on-start can be used to automatically enter the modal command mode on a new tmux session. If you always want to start a new session with the modal command mode, add the following to .tmux.conf:

set -g @modal-on-start on

Always sticky command

The option @modal-always-sticky can be specified to always use the sticky version instead of manually entering the sticky command first (e.g. w w for sticky window command):

set -g @modal-always-sticky on

For example, with this in .tmux.conf, one only has to press w once and the sticky window command mode will be entered directly. That is, after hitting w once, you can now directly use h, j, k and l to select the window panes (or any other window commands). Don't forget to exit the sticky command with q.

Show command keys in status bar

The option @modal-show-cmd-keys can be set in .tmux.conf to give immediate feedback in the status bar during tmux-modal command sequences:

set -g @modal-show-cmd-keys on

The left status bar will now update to match the tmux-modal command currently in use. For example, if you press w the status bar will change from the modal command icon [=] to [w] (the window command). If you now further press s, it will update to [ws] to signify the split window command sequence and so on.

Set custom status bar modal mode icon

The option @modal-cmd-icon can be used to specify any string, which will be the left status bar icon to indicate that modal mode is in use. For example, to use a circle as icon (note the padding at the beginning for a more aesthetically centering in the status bar):

set -g @modal-cmd-icon " 🟢"

Yes/no prompt

DEPRECATED

This option is deprecated due to option @modal-commands-conf and will be removed soon. To keep the old behavior, use option @modal-commands-conf instead. For example:

diff --git a/commands.conf b/commands.conf
index 1859fcb..ec4f65e 100644
--- a/commands.conf
+++ b/commands.conf
@@ -82,7 +82,7 @@ CMD_WIN_PANE_UP='select-pane -U'
 CMD_WIN_PANE_DOWN='select-pane -D'

 ## Delete window pane.
-CMD_WIN_PANE_DEL='kill-pane'
+CMD_WIN_PANE_DEL='confirm-before -p "kill-pane #P? (y/n)" kill-pane'

 ## Select previous window (window command alias for CMD_GOTO_WIN_PREV).
 CMD_WIN_PREV='select-window -t :-'
@@ -91,7 +91,7 @@ CMD_WIN_PREV='select-window -t :-'
 CMD_WIN_NEXT='select-window -t :+'

 ## Delete window.
-CMD_WIN_DEL='kill-window'
+CMD_WIN_DEL='confirm-before -p "kill-window #W? (y/n)" kill-window'

 ## Create new window.
 CMD_WIN_CREATE='new-window'
@@ -183,7 +183,7 @@ CMD_SESS_NEXT='switch-client -n'
 CMD_SESS_TREE='choose-tree -Zs'

 ## Delete session.
-CMD_SESS_DEL='kill-session'
+CMD_SESS_DEL='confirm-before -p "kill-session #S? (y/n)" kill-session'

 # "Go to" command prefix.

Some commands might be too "dangerous" to execute directly, for example w d (kill-pane) or w D (kill-window). The option @modal-yesno-cmd can therefore be used to ask for confirmation before executing the commands (to mimic the default tmux behavior). If you want a yes/no prompt before executing these commands, put this in .tmux.conf:

set -g @modal-yesno-cmd on