[Bug]: Floating window/tab terminal issue affecting custom terminals

[piersolenski]

Similar Issues

• Before filing, I have searched for similar issues.

Neovim Version

NVIM v0.12.0-dev-1019+g013af17ed9-Homebrew
Build type: Release
LuaJIT 2.1.1753364724
Run "nvim -V1 -v" for more info

Multiplexer Integration

tmux

Multiplexer Version

tmux 3.5a

Steps to Reproduce

1. Open Neovim in Tmux
2. Create a terminal :terminal
3. Run any custom program in it, for example LazyGit
4. Open a second tmux pane
5. Attempt to navigate to it

Expected Behavior

I should be able to use custom terminals such as LazyGit, GitUI, etc with this plugin.

Actual Behavior

The cursor randomly focuses somewhere in the first Neovim pane, you have to attempt a second time to get to the tmux pane before you leave Neovim.

Minimal Configuration to Reproduce

local root = vim.fn.fnamemodify('./.repro', ':p')

-- set stdpaths to use .repro
for _, name in ipairs({ 'config', 'data', 'state', 'cache' }) do
  vim.env[('XDG_%s_HOME'):format(name:upper())] = root .. '/' .. name
end

-- bootstrap lazy
local lazypath = root .. '/plugins/lazy.nvim'
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    'git',
    'clone',
    '--filter=blob:none',
    '--single-branch',
    'https://github.com/folke/lazy.nvim.git',
    lazypath,
  })
end
vim.opt.runtimepath:prepend(lazypath)

-- install plugins
local plugins = {
  -- do not remove the colorscheme! it makes testing nicer
  'folke/tokyonight.nvim',
  'mrjones2014/smart-splits.nvim',
  -- add any other pugins here
}

require('lazy').setup(plugins, {
  root = root .. '/plugins',
})

require('smart-splits').setup({
  float_win_behavior = "mux"
})

-- recommended mappings
-- resizing splits
-- these keymaps will also accept a range,
-- for example `10<A-h>` will `resize_left` by `(10 * config.default_amount)`
vim.keymap.set('n', '<A-h>', require('smart-splits').resize_left)
vim.keymap.set('n', '<A-j>', require('smart-splits').resize_down)
vim.keymap.set('n', '<A-k>', require('smart-splits').resize_up)
vim.keymap.set('n', '<A-l>', require('smart-splits').resize_right)
-- moving between splits
vim.keymap.set('n', '<C-h>', require('smart-splits').move_cursor_left)
vim.keymap.set('n', '<C-j>', require('smart-splits').move_cursor_down)
vim.keymap.set('n', '<C-k>', require('smart-splits').move_cursor_up)
vim.keymap.set('n', '<C-l>', require('smart-splits').move_cursor_right)
-- swapping buffers between windows
vim.keymap.set('n', '<leader><leader>h', require('smart-splits').swap_buf_left)
vim.keymap.set('n', '<leader><leader>j', require('smart-splits').swap_buf_down)
vim.keymap.set('n', '<leader><leader>k', require('smart-splits').swap_buf_up)
vim.keymap.set('n', '<leader><leader>l', require('smart-splits').swap_buf_right)

-- add anything else here
vim.opt.termguicolors = true
-- do not remove the colorscheme! it makes testing nicer
vim.cmd([[colorscheme tokyonight]])

Additional Details and/or Screenshots

I make heavy use of toggleterm.nvim in my workflow, not just for standard terminals, but also for launching programs like gitui for example.

An annoyance I ran into is that when I switch from a floating window to a tmux pane, the floating window disappears. I thought perhaps float_win_behavior = "mux" might fix it, but it seems buggy - if I'm in insert mode it won't work, and if I'm in normal mode, it only works the first time I navigate to the tmux pane and back again - the second time it will disappear.

It's important for programs like GitUI/LazyGit etc that they maintain insert mode, otherwise when you refocus Neovim you need to re-enter insert mode each time which is frustrating.

I was able to fix that part of the problem by adding the below to my config:

vim.api.nvim_create_autocmd("FocusGained", {
    callback = function()
        if vim.bo.buftype == "terminal" then
            vim.cmd("startinsert")
        end
    end,
})

My second thought was that I could use tabs for these programs so that the floating window disappearing wasn't an issue:

-- GitUI
local gitui = Terminal:new({
    cmd = "gitui",
    direction = "tab",
    hidden = true,
})

However this brought about a strange problem I can't seem to debug where the first time I try to navigate to tmux pane from the program running in a tabbed terminal, rather than jump to the pane it will randomly focus the cursor somewhere on the running program and it's not until I press it again that it enters the tmux pane.

Navigating back from the tmux pane to the program running in the terminal works fine though, as long as you have the FocusGained code:

2025-08-29.at.20.27.46.mp4

Whilst I use toggleterm.nvim, I've noticed this issue happens when running a normal Neovim terminal in a buffer.

The only way I've been able to get the desired behaviour of switching between the two panes and preserving the running program's functionality is to disable this plugin, which I refuse to do because it's awesome.

[mrjones2014]

Can you check if there is anything interesting in the logs (:SmartSplitsLog, you might also try setting the log level in config) and what does :lua=require('smart-splits.utils').is_floating_window(X) output, where X is a Window ID of a toggleterm window?

[piersolenski]

The log just has lots of instances of [smart-splits.nvim] Auto-detected multiplexer back-end: tmux. :lua=require('smart-splits.utils').is_floating_window(X) is true. But as I mentioned before, this isn't just an issue with toggleterm, it seems to be problematic even if you just use a native Neovim terminal buffer.

One thing I've noticed that might be contributing to it is that without smart-splits.nvim enabled, when I flick between a normal terminal buffer and a tmux pane, it's going into normal mode first, requiring a second invokation of smart splits to get to the tmux pane, as you can see here from my cursor changing:

2025-09-01.at.02.08.25.mp4

With smart-splits.nvim disabled, this is the native behaviour:

2025-09-01.at.02.02.06.mp4

So it would appear that smart-splits.nvim is adding this extra step of escaping into normal mode, which would perhaps explain the behaviour of the cursor going awol when using a GUI.

[mrjones2014]

Gotcha, I don't use neovim terminals so I hadn't noticed it, but it's probably an issue with some of the special nature of terminal buffers?

Are you willing to work on a PR?

[piersolenski]

I had a brief look into it, I could delve further - before I do, do you have any other insights as to what might be happening?

[mrjones2014]

I'm not completely sure off the top of my head, but my best guess is there is some special handling needed for terminal buftype because there are some quirks with mode switching in those buf types, especially if you use vi bindings on the command line.

[piersolenski]

Hmm I disabled vi bindings on the command line and the problem persists - it definitely seems like something to do with smart-splits.nvim initially jumping to normal mode before needing to invoke it a second time to navigate to the tmux split.