README.md

June 9, 2026 · View on GitHub

nvim-luxterm

A floating-window terminal session manager, offering elegant multi-terminal organization, live previews, and intuitive navigation with modern UI design. Manage, switch, and customize multiple terminals effortlessly.

✨ Features

Terminal Session Management
- Create, delete, rename, and switch between multiple terminal sessions
- Automatic cleanup of invalid sessions during Neovim session
- Quick session switching and organization
- Session navigation with next/previous cycling functionality
Modern Floating UI
- Floating window manager with split-pane layout
- Live preview pane showing terminal content with intelligent truncation
- Session list with intuitive navigation and keyboard shortcuts
- Customizable window dimensions and border styles
Intuitive Keybindings
- Global toggle accessible from any mode (normal/terminal)
- Quick actions for create, delete, rename operations
- Vim-style navigation within the session manager
- Direct session navigation with customizable keybindings
Compatibility
- Neovim 0.8.0+ required
- Cross-platform support (Linux, macOS, Windows)
- No external dependencies

📦 Installation

using lazy.nvim

{
  "luxvim/nvim-luxterm",
  config = function()
    require("luxterm").setup({
      -- Optional configuration
      manager_width = 0.8,
      manager_height = 0.8,
      preview_enabled = true,
      auto_hide = true,
      keymaps = {
        toggle_manager = "<C-/>",
      }
    })
  end
}

using packer.nvim

use {
  "luxvim/nvim-luxterm",
  config = function()
    require("luxterm").setup()
  end
}

Using vim-plug

Plug 'luxvim/nvim-luxterm'

Then in your init.lua:

require("luxterm").setup({
  -- Your configuration here
})

🛠️ Configuration

require("luxterm").setup({
  -- Manager window dimensions (0.1 to 1.0)
  manager_width = 0.8,          -- 80% of screen width
  manager_height = 0.8,         -- 80% of screen height
  
  -- Enable live preview pane
  preview_enabled = true,
  
  -- Focus new sessions when created via :LuxtermNew
  focus_on_create = false,
  
  -- Auto-hide floating windows when cursor leaves
  auto_hide = true,
  
  -- Keybinding configuration
  keymaps = {
    toggle_manager = "<C-/>",     -- Toggle session manager
    next_session = "<C-k>",       -- Next session keybinding
    prev_session = "<C-j>",       -- Previous session keybinding
    hide_terminal = "<C-Esc>",    -- Hide active terminal keybinding
    global_session_nav = false,   -- Enable global session navigation
  }
})

🎮 Commands

Command	Description	Example
`:LuxtermToggle`	Toggle the session manager UI	`:LuxtermToggle`
`:LuxtermNew [name]`	Create new terminal session	`:LuxtermNew` or `:LuxtermNew work`
`:LuxtermNext`	Switch to next terminal session	`:LuxtermNext`
`:LuxtermPrev`	Switch to previous terminal session	`:LuxtermPrev`
`:LuxtermKill [pattern]`	Delete session(s) by pattern	`:LuxtermKill` or `:LuxtermKill work`
`:LuxtermList`	List all active sessions	`:LuxtermList`
`:LuxtermStats`	Show performance statistics	`:LuxtermStats`

Session Manager Keybindings

When the session manager is open:

Key	Action
`<Enter>`	Open selected session
`n`	Create new session
`d`	Delete selected session
`r`	Rename selected session
`j/k` or `↓/↑`	Navigate session list
`1-9`	Quick select session by number
`<Esc>`	Close manager

Session Terminal Keybindings

When a terminal session window is open:

Key	Action
Hide key (default `<C-Esc>`)	Close the session window (terminal mode)
Toggle key (default `<C-/>`)	Toggle session manager (normal/terminal mode)

🔧 Lua API

-- Get API after setup
local luxterm = require("luxterm").setup()

-- Create and manage sessions
local session = luxterm.create_session({ name = "work" })
luxterm.delete_session(session.id, { confirm = true })
luxterm.switch_session(session.id)

-- Manager control
luxterm.toggle_manager()
local is_open = luxterm.is_manager_open()

-- Information retrieval
local sessions = luxterm.get_sessions()
local active = luxterm.get_active_session()
local stats = luxterm.get_stats()
local config = luxterm.get_config()

`create_session` Options

Option	Type	Default	Description
`name`	`string`	`"Session N"`	Session name (max 12 characters, truncated if longer)
`activate`	`boolean`	`true`	Make this the active session
`focus_on_create`	`boolean`	`false`	Open session in a floating window immediately

Session Object Methods

-- Session validation and status
session:is_valid()           -- Returns true if session buffer is valid
session:get_status()         -- Returns "running" or "stopped"
session:activate()           -- Make this session the active one

-- Content preview
local preview = session:get_content_preview()  -- Returns array of preview lines

🎨 Customization Examples

Minimal Configuration

require("luxterm").setup({
  preview_enabled = false,      -- Disable preview pane
  manager_width = 0.6,         -- Smaller window
  auto_hide = false,           -- Keep windows open
  keymaps = {
    toggle_manager = "<C-t>",   -- Use Ctrl+T instead
  }
})

nvim-luxterm provides powerful session navigation features that work in both normal and terminal modes:

require("luxterm").setup({
  keymaps = {
    next_session = "<C-k>",         -- Next session
    prev_session = "<C-j>",         -- Previous session
    global_session_nav = true,      -- Enable global navigation (works everywhere)
  }
})

When global_session_nav is enabled, you can cycle through terminal sessions from anywhere in Neovim using the configured keybindings. The navigation automatically opens the selected session in a floating window and closes any previously opened session windows. Session navigation also works from within terminal mode using the same keybindings.

Configuration Presets

The plugin includes built-in configuration presets for common use cases:

-- Apply a preset after setup
require("luxterm.config").apply_preset("minimal")    -- No preview, 40% x 60%
require("luxterm.config").apply_preset("compact")    -- Preview enabled, 60% x 50%
require("luxterm.config").apply_preset("full_screen") -- Preview enabled, 95% x 90%, no auto-hide

Custom Keybindings

-- Additional custom keybindings after setup
vim.keymap.set("n", "<leader>tn", ":LuxtermNew<CR>", { desc = "New terminal" })
vim.keymap.set("n", "<leader>tl", ":LuxtermList<CR>", { desc = "List terminals" })
vim.keymap.set("n", "<leader>tk", ":LuxtermKill<CR>", { desc = "Kill terminal" })
vim.keymap.set("n", "<leader>tj", ":LuxtermNext<CR>", { desc = "Next terminal session" })
vim.keymap.set("n", "<leader>th", ":LuxtermPrev<CR>", { desc = "Previous terminal session" })

🎨 Highlight Groups

All highlight groups use link-based defaults, meaning they automatically adapt to your colorscheme. Override any group to customize:

-- Example: custom highlight overrides
vim.api.nvim_set_hl(0, "LuxtermBorderSelected", { fg = "#ff9e64" })
vim.api.nvim_set_hl(0, "LuxtermSessionNameSelected", { fg = "#7aa2f7", bold = true })

Group	Default Link	Used For
`LuxtermNormal`	`NormalFloat`	Window background
`LuxtermBorder`	`FloatBorder`	Window borders
`LuxtermTitle`	`FloatTitle`	Window titles
`LuxtermSessionNameSelected`	`Title`	Selected session name
`LuxtermSessionSelected`	`Special`	Selected session text
`LuxtermBorderSelected`	`Function`	Selected session border
`LuxtermSessionIconSelected`	`DiagnosticOk`	Selected session icon
`LuxtermSessionName`	`Normal`	Unselected session name
`LuxtermSessionNormal`	`Comment`	Unselected session text
`LuxtermBorderNormal`	`NonText`	Unselected session border
`LuxtermSessionIcon`	`NonText`	Unselected session icon
`LuxtermSessionKey`	`Number`	Session hotkey numbers
`LuxtermMenuIcon`	`Function`	Shortcut bar icons
`LuxtermMenuText`	`Normal`	Shortcut bar text
`LuxtermMenuKey`	`Keyword`	Shortcut bar keys
`LuxtermPreviewTitle`	`Title`	Preview pane headers
`LuxtermPreviewContent`	`Normal`	Preview pane content
`LuxtermPreviewEmpty`	`Comment`	Preview empty state

🐛 Troubleshooting

Common Issues

Session manager doesn't open

Ensure Neovim version is 0.8.0 or higher
Check for conflicting keybindings with :verbose map <C-/>
Verify plugin was properly loaded with :LuxtermStats

Terminal sessions appear empty

Sessions auto-cleanup when terminal buffers are deleted
Use :LuxtermStats to check session count and creation stats
Ensure shell is properly configured (echo $SHELL)

Performance issues

Disable preview pane if experiencing lag: preview_enabled = false
Check stats with :LuxtermStats to monitor resource usage
Large terminal histories may affect preview rendering
Plugin uses debounced refresh timers and batched operations for optimal performance

Debug Information

-- Check plugin status and performance metrics
:LuxtermStats

-- List all sessions with status
:LuxtermList

-- Verify configuration
:lua print(vim.inspect(require("luxterm").get_config()))

-- Test configuration presets
:lua require("luxterm.config").apply_preset("minimal")

🙏 Acknowledgments

nvim-luxterm is part of the LuxVim ecosystem - a high-performance Neovim distribution focused on modern UI design and developer productivity.

📄 License

MIT License – see LICENSE for details.