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:
w l
to select the right panew j
to select the pane beloww 1
to select window 1w o
to 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 c
to create a new windoww D
to delete windoww s k
to split window pane rightw s j
to split window pane beloww d
to delete a panew z
to 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 j
to split window pane belowk
to select the above paned
to delete a panec
to create window0
to select window 0
Hit w r
to enter sticky resize window command:
k
to resize the window pane one step upwardsl
to resize the window pane one step to the rightJ
to resize the window pane multiple steps downwardsH
to resize the window pane multiple steps to the left
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
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 |
Window
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).
Resize
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 |
Session
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 '%%'" |
Go to
Window
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 |
Session
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 |
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