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.

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 want to use alternate key mappings, see the configuration section below.

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

Bundle 'christoomey/vim-tmux-navigator'

Add the following to your tmux.conf file to configure the tmux side of this customization.

# Smart pane switching with awareness of vim splits
bind -n C-h run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-h) || tmux select-pane -L"
bind -n C-j run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-j) || tmux select-pane -D"
bind -n C-k run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-k) || tmux select-pane -U"
bind -n C-l run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-l) || tmux select-pane -R"
bind -n C-\ run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys 'C-\\') || tmux select-pane -l"

Thanks to Christopher Sexton who provided the updated tmux configuration in this blog post.

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.

Add the following to your ~/.vimrc to define your custom maps:

let g:tmux_navigator_no_mappings = 1

nnoremap <silent> {Left-mapping} :TmuxNavigateLeft<cr>
nnoremap <silent> {Down-Mapping} :TmuxNavigateDown<cr>
nnoremap <silent> {Up-Mapping} :TmuxNavigateUp<cr>
nnoremap <silent> {Right-Mapping} :TmuxNavigateRight<cr>
nnoremap <silent> {Previoust-Mapping} :TmuxNavigatePrevious<cr>

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> :TmuxNavigateLeft<cr>.

Alter each of the five lines of the tmux configruation listed above to use your custom mappings. Note each line contains two references to the desired mapping.

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.

This is likely due to conflicting key mappings in your ~/.vimrc. You can use the following search pattern to find conflicting mappings \vn(nore)?map\s+\<c-[hjkl]\>. Any matching lines should be deleted or altered to avoid conflicting with the mappings from the plugin.

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'

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.