Better Tmux and Neovim integration

One moment you're fluidly navigating your Neovim splits with Ctrl + h/j/k/l, the next you're fumbling with Ctrl + b and the arrow keys to get to the next pane in Tmux. It's a classic case of split-personality disorder, but for your terminal workflow.

The goal?

A single, unified set of keybindings that just works, whether you're inside a code file or in a new shell.

Before we can use any fancy plugins, we need a way to manage them. Tmux Plugin Manager (TPM) is the de facto standard for this. It's like having a package manager for your Tmux configuration.

The Vim-Tmux-Navigator Plugin

The Vim-Tmux-Navigator is the perfect solution. It's an intelligent plugin that knows when you're in Neovim and when you're not.

Without this plugin, Ctrl + h in a Neovim session is just a backspace. But outside of Neovim, you want it to move to the pane on the left. The Vim-Tmux-Navigator solves this by using a small shell script check to see what application is running in the current pane.

Neovim user

I am using Lazyvim. Installing vim-tmux-navigator on LazyVim is a great way to enable seamless navigation between Neovim splits and Tmux panes using the same keybindings.

While LazyVim provides a robust default configuration, it's also designed to be easily extended with new plugins.

Adding the plugin

Open Neovim and navigate to your user configuration directory. The path is typically ~/.config/nvim/lua/plugins/ on Linux and macOS: ~/AppData/Local/nvim/lua/plugins/.

Create a new file for the plugin. A good name would be tmux.lua.

Add the plugin specification to the tmux.lua file. The simplest way to do this is to return a table containing the plugin's GitHub repository name.

You can use the official vim-tmux-navigator or the Lua-based nvim-tmux-navigation. The Lua-based version is often preferred in modern Neovim setups for its native integration.

Here's the code for the Lua-based version:

return {
  "alexghergh/nvim-tmux-navigation",
  -- This line ensures the plugin is loaded when you start Neovim
  event = "VeryLazy",
  -- You can add a config function to set up options
  config = function()
    require("nvim-tmux-navigation").setup {
      disable_when_zoomed = true, -- Optional: Keep navigation within Neovim when zoomed
    }
  end,
  -- Here you can set the keymaps. LazyVim will automatically handle the mapping.
  keys = {
    { "", function() require("nvim-tmux-navigation").NvimTmuxNavigateLeft() end, desc = "Tmux navigate left" },
    { "", function() require("nvim-tmux-navigation").NvimTmuxNavigateDown() end, desc = "Tmux navigate down" },
    { "", function() require("nvim-tmux-navigation").NvimTmuxNavigateUp() end, desc = "Tmux navigate up" },
    { "", function() require("nvim-tmux-navigation").NvimTmuxNavigateRight() end, desc = "Tmux navigate right" },
    { "", function() require("nvim-tmux-navigation").NvimTmuxNavigateLastActive() end, desc = "Tmux navigate last active" },
  },
}

LazyVim's default keymaps for <C-h>, <C-j>, <C-k>, and <C-l> are for navigating through buffers. The configuration above will override these for the new tmux navigation.

Save the file and restart Neovim. On startup, LazyVim will detect the new plugin and install it automatically. You'll see a pop-up window showing the installation progress.

Customize the Tmux

For the plugin to work correctly, you also need to configure Tmux to send the navigation commands to Neovim.

Open your Tmux configuration file. This is typically ~/.tmux.conf. And then install Tmux hjkl pane navigator.

Reload your Tmux configuration by running the following command in your terminal.

tmux source-file ~/.tmux.conf

Now, You can use Ctrl-h, Ctrl-j, Ctrl-k, and Ctrl-l to seamlessly navigate between both Neovim splits and Tmux panes without having to use the Tmux prefix.

Bonus: you also can change tab behavior on Google Chrome.