Navigation LazyVim + Terminal + Tmux with Ctrl + h/j/k/l

[cittadhammo]

(this was written by Gemini after our session)

If you find yourself constantly jumping between Neovim splits and Tmux panes, you’ve probably realized that using two different sets of shortcuts is a massive friction point.

The goal is to use Ctrl + h/j/k/l to move everywhere—regardless of whether you are inside a Vim split or a terminal pane. Here is how to set up seamless navigation using the gold-standard vim-tmux-navigator plugin within a LazyVim environment.

1. The Neovim Side (LazyVim)

LazyVim makes plugin management easy. Create a new file at ~/.config/nvim/lua/plugins/tmux-navigation.lua and add the following configuration. This installs the plugin and maps the keys:

return {
  "christoomey/vim-tmux-navigator",
  cmd = {
    "TmuxNavigateLeft",
    "TmuxNavigateDown",
    "TmuxNavigateUp",
    "TmuxNavigateRight",
  },
  keys = {
    { "<c-h>", "<cmd>TmuxNavigateLeft<cr>", desc = "Window Left" },
    { "<c-j>", "<cmd>TmuxNavigateDown<cr>", desc = "Window Down" },
    { "<c-k>", "<cmd>TmuxNavigateUp<cr>", desc = "Window Up" },
    { "<c-l>", "<cmd>TmuxNavigateRight<cr>", desc = "Window Right" },
  },
}

2. The Tmux Side

Next, we need to teach Tmux how to "check" if the current pane is running Vim. If it is, Tmux sends the keypress to Vim; if not, Tmux handles the pane movement itself.

Add this to your ~/.tmux.conf:

# Smart pane switching with awareness of Vim splits.
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'

# Enable native tmux movements while in copy-mode
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

3. Why This Is Better

• Muscle Memory: You stop thinking about "layers." Ctrl-l always moves you to the right, whether it's another code file or a running server in a terminal pane.
• No Prefix Needed: You don't have to hit Ctrl-b first. It’s a single-action movement.
• Smart Detection: It detects fzf and view mode as well, so you don't get stuck in those windows either.

💡 Pro Tip: Regaining "Clear Screen"

Because we remapped Ctrl-l (which usually clears the terminal), you can add this to your tmux.conf to clear the screen using Prefix + Ctrl-l:

bind C-l send-keys 'C-l'