Wezterm + TMUX Integration Question

[sins621]

I wanted to ask if there is compatibility between Wezterm and TMUX using this plugin. When I have the plugin enabled in my Wezterm configuration switching between TMUX panes using ctrl+h,j,k,l. doesn't seem to work anymore. If I disable the plugin in Wezterm then I can switch panes as normal.

Here is my Wezterm config:

local wezterm = require("wezterm")
local smart_splits = wezterm.plugin.require("https://github.com/mrjones2014/smart-splits.nvim")
local config = wezterm.config_builder()
local is_windows = wezterm.target_triple:find("windows") ~= nil

config.color_scheme = "Gruvbox Dark (Gogh)"
config.font = wezterm.font("FiraCode Nerd Font")
config.font_size = 14
config.window_decorations = "TITLE|RESIZE"
config.tab_bar_at_bottom = true
config.use_fancy_tab_bar = false
config.window_close_confirmation = "AlwaysPrompt"
config.term = "wezterm"

if is_windows then
	config.default_prog = { "powershell.exe" }
else
	config.default_prog = { "zsh" }
end

config.hide_tab_bar_if_only_one_tab = true
config.adjust_window_size_when_changing_font_size = false

config.leader = { key = "a", mods = "CTRL", timeout_milliseconds = 1000 }

config.keys = {
	{ key = "v", mods = "LEADER", action = wezterm.action({ SplitVertical = { domain = "CurrentPaneDomain" } }) },
	{ key = "h", mods = "LEADER", action = wezterm.action({ SplitHorizontal = { domain = "CurrentPaneDomain" } }) },
	{ key = "z", mods = "LEADER", action = "TogglePaneZoomState" },
	{ key = "c", mods = "LEADER", action = wezterm.action({ SpawnTab = "CurrentPaneDomain" }) },
	{ key = "1", mods = "LEADER", action = wezterm.action({ ActivateTab = 0 }) },
	{ key = "2", mods = "LEADER", action = wezterm.action({ ActivateTab = 1 }) },
	{ key = "3", mods = "LEADER", action = wezterm.action({ ActivateTab = 2 }) },
	{ key = "4", mods = "LEADER", action = wezterm.action({ ActivateTab = 3 }) },
	{ key = "5", mods = "LEADER", action = wezterm.action({ ActivateTab = 4 }) },
	{ key = "6", mods = "LEADER", action = wezterm.action({ ActivateTab = 5 }) },
	{ key = "7", mods = "LEADER", action = wezterm.action({ ActivateTab = 6 }) },
	{ key = "8", mods = "LEADER", action = wezterm.action({ ActivateTab = 7 }) },
	{ key = "9", mods = "LEADER", action = wezterm.action({ ActivateTab = 8 }) },
	{ key = "&", mods = "LEADER|SHIFT", action = wezterm.action({ CloseCurrentTab = { confirm = true } }) },
	{ key = "d", mods = "LEADER", action = wezterm.action({ CloseCurrentPane = { confirm = true } }) },
	{ key = "x", mods = "LEADER", action = wezterm.action({ CloseCurrentPane = { confirm = true } }) },
	{
		key = "i",
		mods = "ALT",
		action = wezterm.action.ActivateTabRelative(-1),
	},
	-- Navigate to the right tab
	{
		key = "o",
		mods = "ALT",
		action = wezterm.action.ActivateTabRelative(1),
	},
	{
		key = "i",
		mods = "ALT|SHIFT",
		action = wezterm.action.MoveTabRelative(-1),
	},
	-- Navigate to the right tab
	{
		key = "o",
		mods = "ALT|SHIFT",
		action = wezterm.action.MoveTabRelative(1),
	},
}

smart_splits.apply_to_config(config, {
  direction_keys = { 'h', 'j', 'k', 'l' },
  modifiers = {
    move = 'CTRL', -- modifier to use for pane movement, e.g. CTRL+h to move left
    resize = 'ALT', -- modifier to use for pane resize, e.g. ALT+h to resize to the left
  },
})
return config

And my TMUX config:

set -g mouse on

set-option -g default-terminal "wezterm"
set-option -g focus-events on

set -g default-shell /bin/zsh
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'niksingh710/minimal-tmux-status'
set -g base-index 1
setw -g pane-base-index 1

# '@pane-is-vim' is a pane-local option that is set by the plugin on load,
# and unset when Neovim exits or suspends; note that this means you'll probably
# not want to lazy-load smart-splits.nvim, as the variable won't be set until
# the plugin is loaded

# Smart pane switching with awareness of Neovim splits.
bind-key -n C-h if -F "#{@pane-is-vim}" 'send-keys C-h'  'select-pane -L'
bind-key -n C-j if -F "#{@pane-is-vim}" 'send-keys C-j'  'select-pane -D'
bind-key -n C-k if -F "#{@pane-is-vim}" 'send-keys C-k'  'select-pane -U'
bind-key -n C-l if -F "#{@pane-is-vim}" 'send-keys C-l'  'select-pane -R'

# Alternatively, if you want to disable wrapping when moving in non-neovim panes, use these bindings
# bind-key -n C-h if -F '#{@pane-is-vim}' { send-keys C-h } { if -F '#{pane_at_left}'   '' 'select-pane -L' }
# bind-key -n C-j if -F '#{@pane-is-vim}' { send-keys C-j } { if -F '#{pane_at_bottom}' '' 'select-pane -D' }
# bind-key -n C-k if -F '#{@pane-is-vim}' { send-keys C-k } { if -F '#{pane_at_top}'    '' 'select-pane -U' }
# bind-key -n C-l if -F '#{@pane-is-vim}' { send-keys C-l } { if -F '#{pane_at_right}'  '' 'select-pane -R' }

# Smart pane resizing with awareness of Neovim splits.
bind-key -n M-h if -F "#{@pane-is-vim}" 'send-keys M-h' 'resize-pane -L 3'
bind-key -n M-j if -F "#{@pane-is-vim}" 'send-keys M-j' 'resize-pane -D 3'
bind-key -n M-k if -F "#{@pane-is-vim}" 'send-keys M-k' 'resize-pane -U 3'
bind-key -n M-l if -F "#{@pane-is-vim}" 'send-keys M-l' 'resize-pane -R 3'

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 -F \"#{@pane-is-vim}\" 'send-keys C-\\'  'select-pane -l'"
if-shell -b '[ "$(echo "$tmux_version >= 3.0" | bc)" = 1 ]' \
    "bind-key -n 'C-\\' if -F \"#{@pane-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


run '~/.tmux/plugins/tpm/tpm'

I didn't open an issue because I'm not entirely sure if the plugin is intended to integrate these two tools together or if it's just a mistake in my configuration. Any help is appreciated.

[mrjones2014]

It sounds like you're a bit confused about the function of the Wezterm plugin.

Wezterm has built-in terminal multiplexing support. smart-splits.nvim supports Wezterm's multiplexer as a backend.

Tmux is also a terminal multiplexer. You should choose one or the other, as they do the same job (mostly, with some slightly differing features).

If I disable the plugin in Wezterm then I can switch panes as normal.

Right, because then it's falling back to the tmux integration, and Wezterm is not swallowing the key presses. By default, smart-splits.nvim checks for tmux first, because some people use tmux in Wezterm and just disable Wezterm's multiplexer; if tmux is not found, then it tries to set up the Wezterm integration.

So what's happening for you is, smart-splits.nvim is setting itself up to use the tmux integration, but the Wezterm plugin is setting up Wezterm keymaps that are the same as your tmux keymaps, therefore Wezterm swallows the key presses and tmux never receives the key press events.

Personally, I switched from tmux to Wezterm's built-in mux quite a while ago, it's more than sufficient for my needs, and wezterm ssh is quite nice.

tl;dr: the solution is to pick one or the other from tmux or Wezterm's built-in mux. If you choose tmux, don't install the Wezterm plugin, since it isn't needed if you're using tmux.

[sins621]

That makes sense, thanks for the clarification 🙏

[woertsposzibllen4me]

NOTE: this has gone through quite a bit of iterating through edits 🤷

Tmux is also a terminal multiplexer. You should choose one or the other, as they do the same job (mostly, with some slightly differing features).

Not entirely true if you are on Windows and use WSL: there is an argument to be made for having both. Tab 0 for WSL with tmux, Tab 1,2,3... for Windows with wezterm multiplexing.

I wanted this functionality too: to be able to switch between panes with C-hjkl regardless of whether in tmux or wezterm. I don't really care for resizing or swapping as that's much more advanced and infrequent.

I got it working reasonably well with a bit of scripting, the solution implies a few moving parts but is pretty simple and unrestrictive.

P.S.

Due to some inconsitencies in pane navigation on the Windows OS as well as some small delay when switching wezterm panes with this plugin I would recommend using https://github.com/letieu/wezterm-move.nvim for the Window side of things (0 delay and more consitent internal nvim window navigation), then using smart-splits only for WSL. The below instructions apply regardless of that choice, it'll work in both cases !

The wezterm side config:

• We don't want either wezterm plugin enabled at all

Wezterm hotkey

• We want our wezterm hotkey to look like this:

local wezterm = require("wezterm")
keys = {
  {
    key = "h",
    mods = "CTRL",
    action = wezterm.action_callback(function(window, pane)
      local vars = pane:get_user_vars() or {}
      local title = pane:get_title() or ""
      local in_Windows_nvim = vars.in_Windows_nvim
      local in_wsl = vars.in_wsl
      if in_Windows_nvim == "1" or in_wsl == "1" then
        window:perform_action(wezterm.action.SendKey({ key = "h", mods = "CTRL" }), pane)
      else
        window:perform_action(wezterm.action.ActivatePaneDirection("Left"), pane)
      end
    end),
  },

}

This is not gonna work by itself and will require wezterm's pane user variable feature to be used in a certain way.

The WSL (zsh) side config:

• In our .zshrc we setup OSC1337 sequences at start up and at exit to set Wezterm pane variables indicating that we are in WSL (I didn't get this to work for tmux specifically, it's tricky). The escape sequence stays the same but the code might need adjustement for other shells than zsh.

# towards the top of the file
printf "\033]1337;SetUserVar=%s=%s\007" in_wsl $(echo -n 1 | base64)

# towards the bottom
TRAPEXIT() {
  printf "\033]1337;SetUserVar=%s=%s\007" in_wsl $(echo -n 0 | base64)
}

The Neovim side config:

Neovim OSC 1337 sequence issuing:

vim.api.nvim_create_autocmd("VimEnter", {
  callback = function()
    if vim.fn.has("win32") == 1 then -- Only for windows, fitting use case
      local function set_in_windows_nvim(b64_val)
        io.write(string.format("\x1b]1337;SetUserVar=in_Windows_nvim=%s\x07", b64_val))
        io.flush()
      end

      -- set to "1" (MQ==) when Neovim starts
      set_in_windows_nvim("MQ==")

      -- set to "0" (MA==) just before Neovim exits
      vim.api.nvim_create_autocmd("VimLeavePre", {
        callback = function()
          set_in_windows_nvim("MA==")
        end,
      })
    end
  end,
})

Done ..

If we are in nvim or wsl, we let the actual nvim plugin do its magic; if that's not the case, we can use C-hjkl to just switch between wezterm panes regularly.

This seems reasonably robust and shouldn't break in too many edge cases, but you might still have to fix as you go lol 😊

N.B. for the author: this works mainly thanks to the fact that Smart split gets you OUT of neovim within ANY tmux/wezterm pane without requiring any configuration/plugin from their end, and would be nice for such workaround if it stayed being that way ahah :) Ty for the plugin 🙏

[mrjones2014]

I'm glad you figured out something that works for you! But using multiple nested multiplexers is definitely out of scope for the plugin and will not be an officially supported use case.

I'm happy to do what I can to not break your configs, but trying to make this work out of the box for everyone is not realistic.