Skip to content

Instantly share code, notes, and snippets.

@mislav
Last active January 14, 2024 09:41
Star You must be signed in to star a gist
Save mislav/5189704 to your computer and use it in GitHub Desktop.
tmux-vim integration to transparently switch between tmux panes and vim split windows

I use tmux splits (panes). Inside one of these panes there's a Vim process, and it has its own splits (windows).

In Vim I have key bindings C-h/j/k/l set to switch windows in the given direction. (Vim default mappings for windows switching are the same, but prefixed with C-W.) I'd like to use the same keystrokes for switching tmux panes.

An extra goal that I've solved with a dirty hack is to toggle between last active panes with C-\.

Here's how it should work:

  1. If I'm in "vim window 2", going in left (C-h) or down (C-j) direction should switch windows inside vim.
  2. However, if I'm in "vim window 3", going right (C-l) or down (C-j) should select the next tmux pane in that direction.

The solution

The solution has 3 parts:

  1. In ~/.tmux.conf, I bind the keys I want to execute a custom tmux-vim-select-pane command;
  2. tmux-vim-select-pane checks if the foreground process in the current tmux pane is Vim, then forwards the original keystroke to the vim process. Otherwise it simply switches tmux panes.
  3. In Vim, I set bindings for the same keystrokes to a custom function. The function tries to switch windows in the given direction. If the window didn't change, that means there are no more windows in the given direction inside vim, and it forwards the pane switching command to tmux by shelling out to tmux select-pane.

Installation

  • check tmux -V that you have v1.8

  • get the vim-tmux-navigator plugin

  • additional ~/.tmux.conf config & tmux-vim-select-pane script:

    curl -fsSL https://gist.github.com/mislav/5189704/raw/install.sh | bash -e
curl -fsSL https://gist.github.com/mislav/5189704/raw/tmux.conf \
>> ~/.tmux.conf
curl -fsSL https://raw.github.com/mislav/dotfiles/1500cd2/bin/tmux-vim-select-pane \
-o /usr/local/bin/tmux-vim-select-pane
chmod +x /usr/local/bin/tmux-vim-select-pane
# Smart pane switching with awareness of vim splits
bind -n C-k run-shell 'tmux-vim-select-pane -U'
bind -n C-j run-shell 'tmux-vim-select-pane -D'
bind -n C-h run-shell 'tmux-vim-select-pane -L'
bind -n C-l run-shell 'tmux-vim-select-pane -R'
bind -n "C-\\" run-shell 'tmux-vim-select-pane -l'
# Bring back clear screen under tmux prefix
bind C-l send-keys 'C-l'
@nathanaelkane
Copy link

Awesome, been wanting exactly this since I started using tmux, thanks!

@mislav
Copy link
Author

mislav commented Apr 7, 2013

@tarruda: Nice, I picked up a trick or two from your solution. Thanks!

@jfelchner
Copy link

@mislav this is exactly what I have been looking for for a while. Thank you for posting it.

@christoomey
Copy link

@mislav, thanks a ton for this. I just set it up and vastly prefer moving around with it.

I did run into two issues while setting it up that I wanted to document here in case anyone else hits them:

  1. The tmux-vim-select-pane uses a format command added to tmux sometime between 1.7 & 1.8. In order to get this running I had to upgrade my tmux to version 1.8. Very straightforward with brew upgrade tmux.
  2. The pattern match used in the tmux-vim-select-pane script was causing an error. I replaced it with: if [ $cmd = "vim" ]; then and all works as expected.

In addition, I extracted the vim plugin into a standalone repo for use with Vundle, Pathogen, etc. I prefer using Vundle for easy install / uninstall and thought I would share in case anyone else wanted to go that route as well. The standalone plugin repo can be found here.

Thanks again!

@unphased
Copy link

It occurred to me that this could be extended in much the similar way to support the vim-aware creation of windows/panes using a single set of shortcut keys (e.g. Ctrl+\ and Ctrl+- , cf. Ctrl+W,V and Ctrl+A,\ and Ctrl+W,S and Ctrl+A,- for vim window and tmux pane splitting, vertically and horizontally, respectively^2). So that if you are not in vim the shortcuts will make new panes vertically split or horizontally split, and if you are in vim it will make split vim-windows.

I'm not sure if this could ever be worth the trouble as there is the quite conceivable need to make a tmux pane while inside vim. This could obviously be done then with the regular method but then why not just keep using the regular method for all cases? But, for the sake of collapsing shortcuts or creating more overloaded powerful shortcuts, this can be accomplished with the same method.

@shime
Copy link

shime commented Jun 4, 2013

This is just awesome! Thanks for your work! 🍻

I have faced some issues, though, so I thought mentioning them might be helpful for someone:

  • this doesn't work with tmux 1.6 - I'm not sure if it works with 1.7 but it definitely works with 1.8 (there's a script that might help you with installation)
  • curl is not downloading in raw format so it saves HTML response - I've fixed URLs to raw versions in my fork

Thanks once more!

@fphilipe
Copy link

fphilipe commented Jun 9, 2013

Might be worth noting that the tmux-vim-select-pane script relies on bash 4. I had version 3.2 on OS X.

@chriseskow
Copy link

I was able to get this working without needing the tmux-vim-select-pane script by using the tmux's if-shell command:

bind -n C-k if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-k" "select-pane -U"
bind -n C-j if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-j" "select-pane -D"
bind -n C-h if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-h" "select-pane -L"
bind -n C-l if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-l" "select-pane -R"

Just drop that in your .tmux.rc, add the Vim plugin, and you're all set!

Idea came from this mailing list thread: http://comments.gmane.org/gmane.comp.terminal-emulators.tmux.user/4390

@derekprior
Copy link

@eskow, good idea. One less dependency. Here it is with the <C-> command included:

# Smart pane switching with awareness of vim splits
bind -n C-h if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-h" "select-pane -L"
bind -n C-j if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-j" "select-pane -D"
bind -n C-k if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-k" "select-pane -U"
bind -n C-l if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-l" "select-pane -R"
bind -n "C-\\" if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-\\" "select-pane -l"

@erlend
Copy link

erlend commented Jun 19, 2013

Don't know if it's my build of vim or some other part of my configuration, but #{pane_current_command} returns Vim (with capital V). Fixed the issue by using tr, however it's not as elegant as @eskow's original solution.

bind -n C-h if "[ $(tmux display -p '#{pane_current_command}' | tr '[:upper:]' '[:lower:]') = vim ]" "send-keys C-h" "select-pane -L"
bind -n C-j if "[ $(tmux display -p '#{pane_current_command}' | tr '[:upper:]' '[:lower:]') = vim ]" "send-keys C-j" "select-pane -D"
bind -n C-k if "[ $(tmux display -p '#{pane_current_command}' | tr '[:upper:]' '[:lower:]') = vim ]" "send-keys C-k" "select-pane -U"
bind -n C-l if "[ $(tmux display -p '#{pane_current_command}' | tr '[:upper:]' '[:lower:]') = vim ]" "send-keys C-l" "select-pane -R"
bind -n "C-\\" if "[ $(tmux display -p '#{pane_current_command}' | tr '[:upper:]' '[:lower:]') = vim ]" "send-keys C-\\" "select-pane -l"

@niko
Copy link

niko commented Jun 20, 2013

@mislav: Nice idea! @eskow: Even better execution! Thanks.

@mislav
Copy link
Author

mislav commented Jun 22, 2013

Thanks everyone for comments and help! I've updated the instructions to point to @christoomey's plugin. However, I stick by my tmux-vim-select-pane command to avoid the gnarly inline scripts in tmux config (seen in the last few comments). Detecting vim is tricky enough that it deserves its own script.

@debugloop
Copy link

Any ideas on how to get this to work with (remote) tmux sessions inside the first tmux? I tried something along the lines of:

bind -n C-h run "(tmux display-message -p '#{pane_current_command}' | grep -iq vim && tmux send-keys C-h) || tmux select-pane -L"
bind -n C-j run "(tmux display-message -p '#{pane_current_command}' | grep -iq vim && tmux send-keys C-j) || tmux select-pane -D"
bind -n C-k run "(tmux display-message -p '#{pane_current_command}' | grep -iq vim && tmux send-keys C-k) || tmux select-pane -U"
bind -n C-l run "(tmux display-message -p '#{pane_current_command}' | grep -iq vim && tmux send-keys C-l) || tmux select-pane -R"
bind -n C-\ run "(tmux display-message -p '#{pane_current_command}' | grep -iq vim && tmux send-keys 'C-\\') || tmux select-pane -l"
bind -r C-h run "tmux send-keys C-h"
bind -r C-j run "tmux send-keys C-j"
bind -r C-k run "tmux send-keys C-k"
bind -r C-l run "tmux send-keys C-l"
bind -r C-\ run "tmux send-keys 'C-\\'"

but this won't work for some reason. The idea was to get the outer tmuxes to pass through the C-hjkl to the inner instance...

@nathanlippi
Copy link

Thank you for sharing!

I've modified this to work with emacs if anyone is interested:
https://gist.github.com/nathanlippi/5923326

@mislav
Copy link
Author

mislav commented Jul 26, 2013

:palmface: My script relied on bash 4 (thanks @fphilipe). Fixed it so it works on bash 3.2 (often system default)

@svenfuchs
Copy link

Here's a version that doesn't require a vim plugin, and zooms the left/rightmost tmux pane when trying to navigate "over it". I guess it somewhat screws the "toggle between last active panes" behaviour though, not sure.

https://gist.github.com/svenfuchs/6146321

@fphilipe
Copy link

Whenever I switch from vim to a tmux pane, the weird escape sequence ^[[O gets printed at the last cursor position in vim. See this screenshot.

I tracked it down and found out that this happens when I manually do C-a :send-keys C-h. Does anyone know how to prevent this? One possible fix I guess would be to tell vim to redraw when leaving vim.

@amiel
Copy link

amiel commented Apr 25, 2014

Thank you @mislav, @svenfuchs, @christoomey, and everyone else that has contributed to this concept. I like

Here's yet another version: amiel/vim-tmux-navigator

Pros:

  1. Includes @svenfuchs' zoom feature
  2. Works in insert mode (or any mode in vim)

Cons:

  1. Depends on ruby
  2. More complicated setup (vim plugin + external script + tmux.conf)
  3. Drops the toggle between last active panes feature

@hjdivad
Copy link

hjdivad commented May 22, 2014

Thanks everyone. This is really helpful. I've added a version that lets you stick to vim's default window keybindings (eg C-w n rather than C-n).

https://gist.github.com/hjdivad/d7f79b45ac2922336fec

@blueyed
Copy link

blueyed commented Jun 19, 2014

JFI: I've just came up with a pull request for the vim-tmux-navigator plugin, which uses tmux environment instead of detecting vim:
the plugin sets a tmux session environment variable when Vim starts, and unsets it when it exits: christoomey/vim-tmux-navigator#37
(this fixes cases where #{pane_current_command} is e.g. make, when vim got started from a make task).

Copy link

ghost commented Mar 28, 2016

Thank you yor this marvellous idea, and for the implementation! Thank to it, I now use these snippets:

In .vimrc:

function! TmuxMove(direction)
        let wnr = winnr()
        silent! execute 'wincmd ' . a:direction
        " If the winnr is still the same after we moved, it is the last pane
        if wnr == winnr()
                call system('tmux select-pane -' . tr(a:direction, 'phjkl', 'lLDUR'))
        end
endfunction

nnoremap <silent> <c-h> :call TmuxMove('h')<cr>
nnoremap <silent> <c-j> :call TmuxMove('j')<cr>
nnoremap <silent> <c-k> :call TmuxMove('k')<cr>
nnoremap <silent> <c-l> :call TmuxMove('l')<cr>

In .tmux.conf:

bind -n C-k if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-k" "select-pane -U"
bind -n C-j if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-j" "select-pane -D"
bind -n C-h if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-h" "select-pane -L"
bind -n C-l if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-l" "select-pane -R"

It may only work for vim in tmux, and do not handle any issue anywhere, but that works for me.

Thank you again to all contributors!

@KabbAmine
Copy link

Awesome, thanks @sshbio

@zhaohuaxishi
Copy link

Awesome, thanks @sshbio

@touilfarouk
Copy link

Best tmux config for ubuntu and vim ?

@droustchev
Copy link

I came up with a slightly simpler solution than hjdivad, which allows to use vim's default split navigation bindings C-w {h,j,k,l}, here's the gist.
My solution shows how to easily set up key bindings in tmux that require multiple keys, using key-tables.

@paulrougieux
Copy link

paulrougieux commented May 8, 2020

Seamless navigation between vim and tmux splits is great for interactive languages such as bash, python and R. It helps to navigate back and forth between code and experiments at the interactive prompt in combination with slime. Thank you for this, I'm a happier person today.

@TanishBansal
Copy link

Thank you for this amazing idea, ended up here after searching a while trying to solve this issue for a while.
Here's my solution without any plugins, using CTRL-Arrow-keys for seamless navigation between vim splits and tmux-panes.
CTRL-Arrow-keys can be changed hjkl, change keybindings in .vimrc accordingly.

~/.vimrc :

function! TmuxMove(direction)
        let wnr = winnr()
        silent! execute 'wincmd ' . a:direction
        " If the winnr is still the same after we moved, it is the last pane
        if wnr == winnr()
                call system('tmux select-pane -' . tr(a:direction, 'phjkl', 'lLDUR'))
        end
endfunction

nnoremap <silent> <C-Left> :call TmuxMove('h')<cr>
nnoremap <silent> <C-Down> :call TmuxMove('j')<cr>
nnoremap <silent> <C-Up> :call TmuxMove('k')<cr>
nnoremap <silent> <C-Right> :call TmuxMove('l')<cr>

nnoremap <silent> <C-h> :call TmuxMove('h')<cr>
nnoremap <silent> <C-j> :call TmuxMove('j')<cr>
nnoremap <silent> <C-k> :call TmuxMove('k')<cr>
nnoremap <silent> <C-l> :call TmuxMove('l')<cr>

~/.tmux.conf:

is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
    | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|n?vim?x?)(diff)?$'" 
bind -n C-Up run-shell "if $is_vim ; then tmux send-keys C-k ; else tmux select-pane -U; fi"
bind -n C-Down run-shell "if $is_vim ; then tmux send-keys C-j; else tmux select-pane -D; fi"
bind -n C-Left run-shell "if $is_vim ; then tmux send-keys C-h; else tmux select-pane -L; fi"
bind -n C-Right run-shell "if $is_vim ; then tmux send-keys C-l; else tmux select-pane -R; fi"

@eliasnorrby
Copy link

Thanks! I tweaked some of the suggestions here to allow for one set of bindings to navigate between bspwm nodes/tmux panes/vim windows (76c2d72).

@keks24
Copy link

keks24 commented Sep 27, 2022

In .tmux.conf:

bind -n C-k if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-k" "select-pane -U"
bind -n C-j if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-j" "select-pane -D"
bind -n C-h if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-h" "select-pane -L"
bind -n C-l if "[ $(tmux display -p '#{pane_current_command}') = vim ]" "send-keys C-l" "select-pane -R"

I optimised this one in order to open as less subshells as possible. It also does a pseudo substring match by substituting the regular expression g?(view|n?vim?x?)(diff)?$ from the current command. This should be compatible with vi, vim, nvim and their variants:

bind -n C-k if-shell "[ '#{pane_current_command}' != '#{s/g?(view|n?vim?x?)(diff)?$//:#{pane_current_command}}' ]" "send-keys C-k" "select-pane -U"
bind -n C-j if-shell "[ '#{pane_current_command}' != '#{s/g?(view|n?vim?x?)(diff)?$//:#{pane_current_command}}' ]" "send-keys C-j" "select-pane -D"
bind -n C-h if-shell "[ '#{pane_current_command}' != '#{s/g?(view|n?vim?x?)(diff)?$//:#{pane_current_command}}' ]" "send-keys C-h" "select-pane -L"
bind -n C-l if-shell "[ '#{pane_current_command}' != '#{s/g?(view|n?vim?x?)(diff)?$//:#{pane_current_command}}' ]" "send-keys C-l" "select-pane -R"

There is still an issue, when the window panes are synchronised. C-l clears adjacent, open shells and C-j presses enter, which can be very dangerous.

@007kevin
Copy link

Sharing my emacs version with variable pane_current_command (e.g emacs, Emacs, Emacs-v1)

bind -n C-p if "[[ $(tmux display -p '#{pane_current_command}') = [Ee]macs* ]]" "send-keys C-p" "copy-mode; send-keys C-p"
bind -n C-n if "[[ $(tmux display -p '#{pane_current_command}') = [Ee]macs* ]]" "send-keys C-n" "copy-mode; send-keys C-n"
bind -n M-v if "[[ $(tmux display -p '#{pane_current_command}') = [Ee]macs* ]]" "send-keys M-v" "copy-mode; send-keys M-v"
bind -n C-Space if "[[ $(tmux display -p '#{pane_current_command}') = [Ee]macs* ]]" "send-keys C-Space" "copy-mode; send-keys C-Space"

When emacs is the current pane, movement keys will behave as normal. When pane is not emacs, you navigate in copy-mode with the same emacs bindings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment