tmux-navigator

URL: https://github.com/christoomey/vim-tmux-navigator/

When combined with a set of tmux key bindings, the plugin will allow you to navigate seamlessly between vim splits and tmux panes using a consistent set of hotkeys.

warning

To work correctly, you must configure tmux separately.

Usage

This plugin provides the following mappings which allow you to move between vim splits and tmux panes seamlessly.

<ctrl-h> => Left
<ctrl-j> => Down
<ctrl-k> => Up
<ctrl-l> => Right
<ctrl-\> => Previous split

To use alternative key mappings, see plugins.tmux-navigator.settings.no_mappings.

Configure tmux

note

There are two main ways to configure tmux.

Option 1: using a plugin

You can install the vim-tmux-navigator plugin.

If you're using TPM, add this to your tmux config:

  set -g @plugin 'christoomey/vim-tmux-navigator'

If you're using nixos or home-manager to manager tmux, you can use the programs.tmux.plugins option for this:

  plugins.tmux.plugins = [
    pkgs.tmuxPlugins.vim-tmux-navigator
  ];

Option 2: manually specify keybindings

Alternatively, you can specify the keybinding in your tmux config.

If you're using nixos or home-manager to manager tmux, you can use the programs.tmux.extraConfig option for this.

Example config from the upstream docs:

  # Smart pane switching with awareness of vim splits.
  # See: https://github.com/christoomey/vim-tmux-navigator
  is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
    | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|l?n?vim?x?|fzf)(diff)?$'"

  bind-key -n 'C-h' if-shell "$is_vim" 'send-keys C-h'  'select-pane -L'
  bind-key -n 'C-j' if-shell "$is_vim" 'send-keys C-j'  'select-pane -D'
  bind-key -n 'C-k' if-shell "$is_vim" 'send-keys C-k'  'select-pane -U'
  bind-key -n 'C-l' if-shell "$is_vim" 'send-keys C-l'  'select-pane -R'

  # Forwarding <C-\\> needs different syntax, depending on tmux version
  tmux_version='$(tmux -V | sed -En "s/^tmux ([0-9]+(.[0-9]+)?).*/\1/p")'
  if-shell -b '[ "$(echo "$tmux_version < 3.0" | bc)" = 1 ]' \
    "bind-key -n 'C-\\' if-shell \"$is_vim\" 'send-keys C-\\'  'select-pane -l'"
  if-shell -b '[ "$(echo "$tmux_version >= 3.0" | bc)" = 1 ]' \
    "bind-key -n 'C-\\' if-shell \"$is_vim\" 'send-keys C-\\\\'  'select-pane -l'"

  bind-key -T copy-mode-vi 'C-h' select-pane -L
  bind-key -T copy-mode-vi 'C-j' select-pane -D
  bind-key -T copy-mode-vi 'C-k' select-pane -U
  bind-key -T copy-mode-vi 'C-l' select-pane -R
  bind-key -T copy-mode-vi 'C-\' select-pane -l

See the upstream docs for more info.