tmux + neovim: fix every :checkhealth warning

Run :checkhealth in neovim inside tmux on a default setup and you get a wall of warnings. Every one of them is real, every one has a one-line fix, and this page is all of them in one place.

The four config lines checkhealth wants

These resolve the standard warnings — Esc lag, autoread not firing, wrong $TERM, and no true color:

~/.tmux.conf
set -sg escape-time 10
set -g focus-events on
set -g default-terminal "tmux-256color"
set -ga terminal-features ",*:RGB"

What each one actually fixes

escape-time: tmux holds Esc for 500ms by default deciding if it's an escape sequence — that's the mode-switch lag you feel. focus-events: without it, neovim never hears FocusGained/FocusLost, so autoread doesn't refresh files changed by another pane (your test runner, a formatter, git). The terminal pair: see the colors guide for the mechanism — inside neovim, also :set termguicolors.

Seamless split navigation

The dream: C-h/j/k/l moves between neovim splits and tmux panes as if they were one system. vim-tmux-navigator does exactly this (install the plugin in neovim, paste its tmux-side bindings into .tmux.conf). If you use lazy.nvim:

lazy.nvim plugin spec
{ "christoomey/vim-tmux-navigator",
  cmd = { "TmuxNavigateLeft", "TmuxNavigateDown",
          "TmuxNavigateUp", "TmuxNavigateRight" },
  keys = {
    { "<c-h>", "<cmd>TmuxNavigateLeft<cr>" },
    { "<c-j>", "<cmd>TmuxNavigateDown<cr>" },
    { "<c-k>", "<cmd>TmuxNavigateUp<cr>" },
    { "<c-l>", "<cmd>TmuxNavigateRight<cr>" },
  } }

Undercurl (squiggly underlines)

LSP diagnostics draw as plain underlines instead of squiggles inside tmux unless you declare the capability:

~/.tmux.conf
set -ga terminal-features ",*:usstyle"

Clipboard

set -g set-clipboard on in tmux plus a normal neovim clipboard setup (vim.o.clipboard = 'unnamedplus') covers local and SSH use in modern terminals. If yanks aren't reaching the system clipboard over SSH, your terminal's OSC 52 support is the suspect — see the system clipboard page for the per-terminal story.

The philosophical question

"Why not just use neovim's own :terminal and splits?" Fair — until you need detach/reattach over SSH, or a pane that survives neovim restarting. The honest split: neovim owns editing layout, tmux owns processes and persistence. The navigator plugin makes the boundary invisible, which is why this combination remains the default stack for terminal-first development.

Verified against tmux 3.6 · updated July 2026 · more guides · cheat sheet

[tmuxlab]
^B