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.
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:
w lto select the right panew jto select the pane beloww 1to select window 1w oto go back to other/last windows
Management
Create and delete windows with a breeze. Split, delete, zoom, move and break panes and much more in just a few keystrokes:
w cto create a new windoww Dto delete windoww s kto split window pane rightw s jto split window pane beloww dto delete a panew zto zoom in/out of a pane
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).
Hit w w to enter sticky window command:
s jto split window pane belowkto select the above panedto delete a panecto create window0to select window 0
Hit w r to enter sticky resize window command:
kto resize the window pane one step upwardslto resize the window pane one step to the rightJto resize the window pane multiple steps downwardsHto resize the window pane multiple steps to the left
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).
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.
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.)
| Keybinding | Description | tmux Command |
|---|---|---|
M-m |
Enter modal command mode. | - |
M-m |
Exit modal command mode. | - |
y |
Paste buffer (e.g. from copy mode). | paste-buffer |
c |
Enter copy-mode. | copy-mode |
q |
Quit sticky command. | - |
: |
Open tmux command mode. | command-prompt |
| Keybinding | Description | tmux Command |
|---|---|---|
w w |
Enter sticky window command mode. | - |
w 0 |
Go to window 0. This is an alias for g w 0. |
select-window -t :0 |
w 1 |
Go to window 1. This is an alias for g w 1. |
select-window -t :1 |
w 2 |
Go to window 2. This is an alias for g w 2. |
select-window -t :2 |
w 3 |
Go to window 3. This is an alias for g w 3. |
select-window -t :3 |
w 4 |
Go to window 4. This is an alias for g w 4. |
select-window -t :4 |
w 5 |
Go to window 5. This is an alias for g w 5. |
select-window -t :5 |
w 6 |
Go to window 6. This is an alias for g w 6. |
select-window -t :6 |
w 7 |
Go to window 7. This is an alias for g w 7. |
select-window -t :7 |
w 8 |
Go to window 8. This is an alias for g w 8. |
select-window -t :8 |
w 9 |
Go to window 9. This is an alias for g w 9. |
select-window -t :9 |
w t |
Select window with tree view. This is an alias for g w t. |
choose-tree -Zw |
w i |
Select window with index. This is an alias for g w i. |
command-prompt -p index "select-window -t ':%%'" |
w h |
Select left pane. | select-pane -L |
w l |
Select right pane. | select-pane -R |
w k |
Select above pane. | select-pane -U |
w j |
Select below pane. | select-pane -D |
w d |
Delete window pane. | kill-pane |
w H |
Select previous window. This is an alias for g w h. |
select-window -t :- |
w L |
Select next window. This is an alias for g w l. |
select-window -t :+ |
w D |
Delete window. | kill-window |
w c |
Create new window. | new-window |
w o |
Select other/last window. | last-window |
w z |
Zoom pane. | resize-pane -Z |
w b |
Break pane into a new window. | break-pane |
w n |
Display pane numbers. | display-panes |
w , |
Rename window. | command-prompt -I "#W" "rename-window -- '%%'" |
w s l |
Split window pane right. | split-window -h |
w s j |
Split window pane down. | split-window |
w m k |
Move window pane up. | swap-pane -U |
w m j |
Move window pane down. | swap-pane -D |
w a 1 |
Arrange window to layout 1. | select-layout even-horizontal |
w a 2 |
Arrange window to layout 2. | select-layout even-vertical |
w a 3 |
Arrange window to layout 3. | select-layout main-horizontal |
w a 4 |
Arrange 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).
| Keybinding | Description | tmux Command |
|---|---|---|
w r |
Enter sticky resize window command | - |
When in sticky resize window command, the following resizes the window (as
usual, q exits the sticky command).
| Keybinding | Description | tmux Command |
|---|---|---|
h |
Resizes the window pane one step to the left. | resize-pane -L |
l |
Resizes the window pane one step to the right. | resize-pane -R |
j |
Resizes the window pane one step downwards. | resize-pane -D |
k |
Resizes the window pane one step upwards. | resize-pane -U |
H |
Resizes the window pane multiple steps to the left. | resize-pane -L 5 |
L |
Resizes the window pane multiple steps to the right. | resize-pane -R 5 |
J |
Resizes the window pane multiple steps downwards. | resize-pane -D 5 |
K |
Resizes the window pane multiple steps upwards. | resize-pane -U 5 |
| Keybinding | Description | tmux Command |
|---|---|---|
s d |
Detach session. | detach-client |
s h |
Select previous session. This is an alias for g s h. |
switch-client -p |
s l |
Select next session. This is an alias for g s l. |
switch-client -n |
s t |
Select session with tree view. This is an alias for g s t. |
choose-tree -Zs |
s D |
Delete session. | kill-session |
s , |
Rename session. | command-prompt -I "#S" "rename-session '%%'" |
| Keybinding | Description | tmux Command |
|---|---|---|
g w 0 |
Go to window 0. | select-window -t :0 |
g w 1 |
Go to window 1. | select-window -t :1 |
g w 2 |
Go to window 2. | select-window -t :2 |
g w 3 |
Go to window 3. | select-window -t :3 |
g w 4 |
Go to window 4. | select-window -t :4 |
g w 5 |
Go to window 5. | select-window -t :5 |
g w 6 |
Go to window 6. | select-window -t :6 |
g w 7 |
Go to window 7. | select-window -t :7 |
g w 8 |
Go to window 8. | select-window -t :8 |
g w 9 |
Go to window 9. | select-window -t :9 |
g w t |
Go to window with tree view. | choose-tree -Zw |
g w i |
Go to window with index. | command-prompt -p index "select-window -t ':%%'" |
g w h |
Go to previous window. | select-window -t :- |
g w l |
Go to next window. | select-window -t :+ |
g w o |
Go to other/last window. | last-window |
| Keybinding | Description | tmux Command |
|---|---|---|
g s h |
Go to previous session. | switch-client -p |
g s l |
Go to next session. | switch-client -n |
g s t |
Go to session with tree view. | choose-tree -Zs |
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
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
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
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.
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.
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 " 🟢"
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