https://github.com/gh-liu/nvim-winterm
Multi-terminal window manager.
https://github.com/gh-liu/nvim-winterm
Last synced: 3 months ago
JSON representation
Multi-terminal window manager.
- Host: GitHub
- URL: https://github.com/gh-liu/nvim-winterm
- Owner: gh-liu
- License: mit
- Created: 2026-01-15T09:38:08.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-22T05:46:54.000Z (3 months ago)
- Last Synced: 2026-01-22T16:52:21.939Z (3 months ago)
- Language: Lua
- Homepage:
- Size: 43 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-neovim - gh-liu/nvim-winterm - Multi-terminal window manager. (Terminal Integration / CSV Files)
- awesome-neovim-sorted - gh-liu/nvim-winterm - terminal window manager. | (Terminal Integration)
README
# nvim-winterm
Multi-terminal window manager.
## Installation
### lazy.nvim
```lua
{
"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:
```lua
{
"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.
```lua
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)
```