Based on repository activity, growth velocity and community engagement.
62
Growth30/30
Activity4/25
Popularity18/25
Trust11/20
6,304
Stars
High
Sentiment
Is this actually an AI agent?
6,304
README.md
Vim Tmux Navigator
This plugin is a repackaging of Mislav Marohnić's tmux-navigator
configuration described in this gist. When combined with a set of tmux
key bindings, the plugin will allow you to navigate seamlessly between
vim and tmux splits using a consistent set of hotkeys.
NOTE: This requires tmux v1.8 or higher.
Usage
This plugin provides the following mappings which allow you to move between
Vim panes and tmux splits seamlessly.
<ctrl-h> => Left
<ctrl-j> => Down
<ctrl-k> => Up
<ctrl-l> => Right
<ctrl-\> => Previous split
Note - you don't need to use your tmux prefix key sequence before using
the mappings.
If you don't have a preferred installation method, I recommend using Vundle.
Assuming you have Vundle installed and configured, the following steps will
install the plugin:
Add the following line to your ~/.vimrc file
Plugin 'christoomey/vim-tmux-navigator'
Then run
:PluginInstall
If you are using Vim 8+, you don't need any plugin manager. Simply clone this repository inside ~/.vim/pack/plugin/start/ directory and restart Vim.
If you prefer, you can use the Tmux Plugin Manager (TPM) instead of
copying the snippet.
When using TPM, add the following lines to your ~/.tmux.conf:
set -g @plugin 'christoomey/vim-tmux-navigator'
To set a different key-binding, use the plugin configuration settings
(remember to update your vim config accordingly).
Multiple key bindings are possible, use a space to separate.
set -g @vim_navigator_mapping_left "C-Left C-h" # use C-h and C-Left
set -g @vim_navigator_mapping_right "C-Right C-l"
set -g @vim_navigator_mapping_up "C-k"
set -g @vim_navigator_mapping_down "C-j"
set -g @vim_navigator_mapping_prev "" # removes the C-\ binding
To disable the automatic mapping of <prefix> C-l to send C-l (which is
intended to restore the "clear screen" functionality):
set -g @vim_navigator_prefix_mapping_clear_screen ""
You can also customize how tmux detects instances of vim. Override the
following options:
# Change the regular expression used to detect vim. This pattern must be
# compatible with `grep -iE` extended regular expression syntax.
set -g @vim_navigator_pattern '(\S+/)?g?\.?(view|l?n?vim?x?|fzf)(diff)?(-wrapped)?'
# Override the shell script logic for detecting vim. Instances of
# '@vim_navigator_pattern' will automatically be substituted with your override
# of '@vim_navigator_pattern', or it will use the default @vim_navigator_pattern
# if you haven't overridden the option.
is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
| grep -iqE '^[^TXZ ]+ +@vim_navigator_pattern$'"
set -g @vim_navigator_check "${is_vim}"
Don't forget to run tpm:
run '~/.tmux/plugins/tpm/tpm'
Thanks to Christopher Sexton who provided the updated tmux configuration in
this blog post.
Configuration
Custom Key Bindings
If you don't want the plugin to create any mappings, you can use the five
provided functions to define your own custom maps. You will need to define
custom mappings in your ~/.vimrc as well as update the bindings in tmux to
match.
Vim
Add the following to your ~/.vimrc to define your custom maps:
Note Each instance of {Left-Mapping} or {Down-Mapping} must be replaced
in the above code with the desired mapping. Ie, the mapping for <ctrl-h> =>
Left would be created with nnoremap <silent> <c-h> :<C-U>TmuxNavigateLeft<cr>.
Autosave on leave
You can configure the plugin to write the current buffer, or all buffers, when
navigating from Vim to tmux. This functionality is exposed via the
g:tmux_navigator_save_on_switch variable, which can have either of the
following values:
Value | Behavior
------ | ------
1 | :update (write the current buffer, but only if changed)
2 | :wall (write all buffers)
To enable this, add the following (with the desired value) to your ~/.vimrc:
" Write all buffers before navigating from Vim to tmux pane
let g:tmux_navigator_save_on_switch = 2
Disable While Zoomed
By default, if you zoom the tmux pane running Vim and then attempt to navigate
"past" the edge of the Vim session, tmux will unzoom the pane. This is the
default tmux behavior, but may be confusing if you've become accustomed to
navigation "wrapping" around the sides due to this plugin.
We provide an option, g:tmux_navigator_disable_when_zoomed, which can be used
to disable this unzooming behavior, keeping all navigation within Vim until the
tmux pane is explicitly unzoomed.
To disable navigation when zoomed, add the following to your ~/.vimrc:
" Disable tmux navigator when zooming the Vim pane
let g:tmux_navigator_disable_when_zoomed = 1
If you are using TPM, you can also configure this behavior on the tmux side by
adding the following to your ~/.tmux.conf:
set -g @tmux_navigator_disable_when_zoomed "1"
This will prevent navigation to other tmux panes when the current pane is zoomed.
Preserve Zoom
As noted above, navigating from a Vim pane to another tmux pane normally causes
the window to be unzoomed. Some users may prefer the behavior of tmux's -Z
option to select-pane, which keeps the window zoomed if it was zoomed. To
enable this behavior, set the g:tmux_navigator_preserve_zoom option to 1:
" If the tmux window is zoomed, keep it zoomed when moving from Vim to another pane
let g:tmux_navigator_preserve_zoom = 1
Naturally, if g:tmux_navigator_disable_when_zoomed is enabled, this option
will have no effect.
Tmux
Alter each of the five lines of the tmux configuration listed above to use your
custom mappings. Note each line contains two references to the desired
mapping.
Additional Customization
Ignoring programs that use Ctrl+hjkl movement
In interactive programs such as FZF or the built-in Vim terminal, Ctrl+hjkl can be used instead of the arrow keys to move the selection up and down. If vim-tmux-navigator is getting in your way trying to change the active window instead, you can make it be ignored and work as if this plugin were not enabled. Just modify the is_vim variable(that you have either on the snipped you pasted on ~/.tmux.conf or on the vim-tmux-navigator.tmux file). For example, to add the program foobar:
- vim_pattern='(\S+/)?g?\.?(view|l?n?vim?x?|fzf)(diff)?(-wrapped)?'
+ vim_pattern='(\S+/)?g?\.?(view|l?n?vim?x?|fzf|foobar)(diff)?(-wrapped)?'
is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
| grep -iqE '^[^TXZ ]+ +${vim_pattern}$'"
# Or, use the plugin config option:
set -g @vim_navigator_pattern '(\S+/)?g?\.?(view|l?n?vim?x?|fzf|foobar)(diff)?(-wrapped)?'
Restoring Clear Screen (C-l)
The default key bindings include <Ctrl-l> which is the readline key binding
for clearing the screen. The following binding can be added to your ~/.tmux.conf file to provide an alternate mapping to clear-screen.
bind C-l send-keys 'C-l'
With this enabled you can use <prefix> C-l to clear the screen.
Thanks to Brian Hogan for the tip on how to re-map the clear screen binding.
Restoring SIGQUIT (C-\)
The default key bindings also include <Ctrl-\> which is the default method of
sending SIGQUIT to a foreground process. Similar to "Clear Screen" above, a key
binding can be created to replicate SIGQUIT in the prefix table.
bind C-\\ send-keys 'C-\'
Alternatively, you can exclude the previous pane key binding from your ~/.tmux.conf. If using TPM, the following line can be used to unbind the previous pane binding set by the plugin.
unbind -n C-\\
Disable Wrapping
By default, if you try to move past the edge of the screen, tmux/vim will
"wrap" around to the opposite side. To disable this, you'll need to
configure both tmux and vim:
For vim, you only need to enable this option:
let g:tmux_navigator_no_wrap = 1
Tmux doesn't have an option, so whatever key bindings you have need to be set
to conditionally wrap based on position on screen:
If you like to nest your tmux sessions, this plugin is not going to work
properly. It probably never will, as it would require detecting when Tmux would
wrap from one outermost pane to another and propagating that to the outer
session.
By default this plugin works on the outermost tmux session and the vim
sessions it contains, but you can customize the behaviour by adding more
commands to the expression used by the grep command.
When nesting tmux sessions via ssh or mosh, you could extend it to look like:
- vim_pattern='(\S+/)?g?\.?(view|l?n?vim?x?|fzf)(diff)?(-wrapped)?'
+ vim_pattern='(\S+/)?g?\.?(view|l?n?vim?x?|fzf|ssh|mosh)(diff)?(-wrapped)?'
# Or, use the plugin config option:
set -g @vim_navigator_pattern '(\S+/)?g?\.?(view|l?n?vim?x?|fzf|ssh|mosh)(diff)?(-wrapped)?'
This configuration makes this plugin work within the innermost tmux session and
the vim sessions within that one. This works better than the default behaviour
if you use the outer Tmux sessions as relays to different hosts and have all
instances of vim on remote hosts.
Similarly, if you like to nest tmux locally, add |tmux to the expression.
This behaviour means that you can't leave the innermost session with Ctrl-hjkl
directly. These following fallback mappings can be targeted to the right Tmux
session by escaping the prefix (Tmux' send-prefix command).
bind -r C-h run "tmux select-pane -L"
bind -r C-j run "tmux select-pane -D"
bind -r C-k run "tmux select-pane -U"
bind -r C-l run "tmux select-pane -R"
bind -r C-\ run "tmux select-pane -l"
Another workaround is to configure tmux on the outer machine to send keys to
the inner tmux session:
Here we bind "meta" key (aka "alt" or "option" key) combinations for each of
the four directions and send those along to the innermost session via
send-keys. You use the normal C-h,j,k,l while in the outermost session and
the alternative bindings to navigate the innermost session. Note that if you
use the example above on a Mac, you may need to configure your terminal app to
get the option key to work like a normal meta key. Consult your terminal app's
manual for details.
A third possible solution is to manually prevent the outermost tmux session
from intercepting the navigation keystrokes by disabling the prefix table:
set -g pane-active-border-style 'fg=#000000,bg=#ffff00'
bind -T root F12 \
set prefix None \;\
set key-table off \;\
if -F '#{pane_in_mode}' 'send-keys -X cancel' \;\
set -g pane-active-border-style 'fg=#000000,bg=#00ff00'
refresh-client -S \;\
bind -T off F12 \
set -u prefix \;\
set -u key-table \;\
set -g pane-active-border-style 'fg=#000000,bg=#ffff00'
refresh-client -S
This code, added to the machine running the outermost tmux session, toggles the
outermost prefix table on and off with the F12 key. When off, the active
pane's border changes to green to indicate that the inner session receives
navigation keystrokes. When toggled back on, the border returns to yellow and
normal operation resumes and the outermost responds to the nav keystrokes.
The code example above also toggles the prefix key (ctrl-b by default) for the
outer session so that same prefix can be temporarily used on the inner session
instead of having to use a different prefix (ctrl-a by default) which you may
find convenient. If not, simply remove the lines that set/unset the prefix key
from the code example above.
netrw
Vim's builtin file explorer, named the netrw plugin, has a default keymapping
for <C-l>. When using vim-tmux-navigator with default settings,
vim-tmux-navigator will try to override the netrw mapping so that <C-l> will
still be mapped to :TmuxNavigateRight as it is for other buffers. If you
prefer to keep the netrw mapping, set this variable in your vimrc:
let g:tmux_navigator_disable_netrw_workaround = 1
Alternatively, if you prefer to work around the issue yourself, you can add the
following to your vimrc:
let g:tmux_navigator_disable_netrw_workaround = 1
" g:Netrw_UserMaps is a list of lists. If you'd like to add other key mappings,
" just add them like so: [['a', 'command1'], ['b', 'command2'], ...]
let g:Netrw_UserMaps = [['<C-l>', '<C-U>TmuxNavigateRight<cr>']]
Faster performance
By default, this plugin relies on ps -o state= -o comm= -t to detect whether
the current pane is running vim or not. If the ps command is slow, then you
may be able to optimize the performance in common cases by customizing
@vim_navigator_check like so:
This is likely due to conflicting key mappings in your ~/.vimrc. You can check
this by running :verbose nmap <C-h> (similar for each of the key bindings).
You should see vim-tmux-runner as the source listed for the key binding, but if
you see something else, you've got a conflict and will need to remove the other
key binding or otherwise restructure your vim config.
Another option is that the pattern matching included in the .tmux.conf is
not recognizing that Vim is active. To check that tmux is properly recognizing
Vim, use the provided Vim command :TmuxNavigatorProcessList. The output of
that command should be a list like:
Ss -zsh
S+ vim
S+ tmux
If you encounter a different output please open an issue with as much info
about your OS, Vim version, and tmux version as possible.
Tmux Can't Tell if Vim Is Active
This functionality requires tmux version 1.8 or higher. You can check your
version to confirm with this shell command:
tmux -V # should return 'tmux 1.8'
Switching out of Vim Is Slow
If you find that navigation within Vim (from split to split) is fine, but Vim
to a non-Vim tmux pane is delayed, it might be due to a slow shell startup.
Consider moving code from your shell's non-interactive rc file (e.g.,
~/.zshenv) into the interactive startup file (e.g., ~/.zshrc) as Vim only
sources the non-interactive config.
It doesn't work in Vim's terminal mode
Terminal mode is now supported :)
It Doesn't Work in tmate
tmate is a tmux fork that aids in setting up remote pair programming
sessions. It is designed to run alongside tmux without issue, but occasionally
there are hiccups. Specifically, if the versions of tmux and tmate don't match,
you can have issues. See this
issue for more
detail.
Switching between host panes doesn't work when docker is running
Images built from minimalist OSes may not have the ps command or have a
simpler version of the command that is not compatible with this plugin.
Try installing the procps package using the appropriate package manager
command. For Alpine, you would do apk add procps.
If this doesn't solve your problem, you can also try the following:
Replace the is_vim variable in your ~/.tmux.conf file with:
vim_pattern='(\S+/)?g?\.?(view|l?n?vim?x?|fzf)(diff)?(-wrapped)?'
if-shell '[ -f /.dockerenv ]' \
"is_vim=\"ps -o state=,comm= -t '#{pane_tty}' \
| grep -iqE '^[^TXZ ]+ +${vim_pattern}$'\""
# Filter out docker instances of nvim from the host system to prevent
# host from thinking nvim is running in a pseudoterminal when its not.
"is_vim=\"ps -o state=,comm=,cgroup= -t '#{pane_tty}' \
| grep -ivE '^.+ +.+ +.+\\/docker\\/.+$' \
| grep -iqE '^[^TXZ ]+ +${vim_pattern}$'\""
# Or, use the plugin config option:
if-shell '[ -f /.dockerenv ]' \
"is_vim=\"ps -o state=,comm= -t '#{pane_tty}' \
| grep -iqE '^[^TXZ ]+ +@vim_navigator_pattern$'\""
# Filter out docker instances of nvim from the host system to prevent
# host from thinking nvim is running in a pseudoterminal when its not.
"is_vim=\"ps -o state=,comm=,cgroup= -t '#{pane_tty}' \
| grep -ivE '^.+ +.+ +.+\\/docker\\/.+$' \
| grep -iqE '^[^TXZ ]+ +@vim_navigator_pattern$'\""
set -g @vim_navigator_check "${is_vim}"
Details: The output of the ps command on the host system includes processes
running within containers, but containers have their own instances of
/dev/pts/*. vim-tmux-navigator relies on /dev/pts/* to determine if vim is
running, so if vim is running in say /dev/pts/<N> in a container and there is a
tmux pane (not running vim) in /dev/pts/<N> on the host system, then without
the patch above vim-tmux-navigator will think vim is running when its not.
It Still Doesn't Work!!!
The tmux configuration uses an inlined grep pattern match to help determine if
the current pane is running Vim. If you run into any issues with the navigation
not happening as expected, you can try using Mislav's original external
script which has a more robust check.
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.
