gh-liu/nvim-winterm

github

terminal-integration

5

1

1

0

CREATED

2026-01-15

UPDATED

2026-01-27

---

nvim-winterm

Multi-terminal window manager.

Installation

lazy.nvim

{
    "gh-liu/nvim-winterm",
    opts = {
        win = {
            height = 0.3,
        },
    },
},

Configuration

Options

• win.height: Window height as a ratio of screen lines (default 0.3)
• autofocus: Auto focus terminal window after running command (default true)
• autoinsert: Auto enter insert mode when focusing terminal (default false)

Example:

{
    "gh-liu/nvim-winterm",
    opts = {
        win = {
            height = 0.3,
        },
        autofocus = true,
        autoinsert = false,
    },
}

Highlight

Winbar uses its own highlight groups, linked to TabLine by default:

• WintermWinbar -> TabLine
• WintermWinbarSel -> TabLineSel

Commands

• :Winterm: Toggle the window (opens a shell the first time)
• :Winterm {cmd}: Create a terminal running {cmd}
• :Winterm -dir={path} {cmd}: Create a terminal in {path} (default uses getcwd())
• :Winterm [N] or :[N]Winterm: Focus terminal by index
• :Winterm! [N] or :[N]Winterm!: Kill terminal (force with !)

For relative navigation, +N/-N works with focus/kill arguments (e.g. :Winterm -1 or :Winterm! +1). For absolute index, pass it as an argument or a count (e.g. :Winterm 3 or :3Winterm).

-dir supports these forms:

• -dir=path
• -dir="path with spaces"
• -dir='path with spaces'

Lua API

run() returns a stable term object (identified by bufnr). Use list() to get all terms.

local winterm = require("winterm")

local term = winterm.run("npm run dev", { focus = false })
if term then
    term:focus()
end

vim.ui.select(winterm.list(), {
    prompt = "Winterm terminals",
    format_item = function(item)
        return string.format("%s  (%s)", item.cmd, item.cwd or "")
    end,
}, function(choice)
    if choice then
        choice:focus()
    end
end)