Minh-Tri Le

01The Problem: Leaving the Editor for a Terminal

Every Neovim user has a workflow that involves a terminal. Running tests, checking git logs, starting dev servers - these things happen constantly. The question is how you get to a terminal without breaking your concentration.

The common approaches all have trade-offs. A separate terminal window means alt-tabbing - a context switch that adds up. A built-in :terminal split takes up permanent screen real estate. Tmux panes help, but require a context switch of a different kind.

What I wanted was simpler: press a key, a floating terminal appears centered on my screen. Press it again, it disappears. My code is still exactly where I left it. The terminal session persists - same shell, same directory, same history - I just can't see it until I need it. And when I need a second session (say, one for tests and one for a dev server), I want to spin it up with a single keymap and switch between them without leaving the editor.

02Why Write My Own Plugin?

There are toggle-terminal plugins out there - toggleterm.nvim being the most popular. But popular plugins come with surface area: multiple terminal types, split modes, shade options, send-to-terminal integrations. All useful features, but not the ones I needed.

After building nvim-pomodoro (which also uses a floating popup), I had a solid foundation in Neovim's floating window API. This plugin pushed that knowledge further: handling terminal buffers specifically, managing insert mode transitions, dealing with the edge cases that come with jobstart and job exit callbacks, and now maintaining a session list with a winbar tab bar for navigation.

The result is a plugin small enough to read in one sitting - one file, ~300 lines - and exactly as capable as I need it to be.

03Design Principles

Buffer Reuse

Each session gets its own buffer (bufhidden=hide). Close the window and the buffer lives on - reopen it and the same shell, same directory, same history is exactly where you left it. Switching between sessions swaps the buffer via nvim_win_set_buf with no window teardown.

Auto-Resize

The floating window geometry is computed as a fraction of vim.o.columns / vim.o.lines. A VimResized autocmd fires on editor resize and recalculates position and size automatically.

Single File

The entire plugin is ~300 lines in one file: init.lua. Read it to understand it. Modify it to own it. No layers of abstraction between you and the behaviour.

nvim-toggleterm/

└── lua/nvim-toggleterm/

└── init.lua -- Everything: setup(), open/close/toggle(), new/close/rename/switch_terminal()

04Features

The Window

Floating & centered
Opens over your code - no split, no tab, no layout shift.
Proportional sizing
Width and height set as fractions of the editor dimensions.
Six border styles
single, double, rounded, solid, shadow, or a custom set.
Auto-resize
Re-centers and rescales on VimResized, always proportional.

Sessions

Multiple named terminals
Each session keeps its own buffer, shell, history, and cwd.
Winbar tab bar
All active sessions listed; the current one is highlighted.
Full session control
Create, rename, close, and switch via commands or buffer-local keymaps.
Auto-close on exit
When the shell job ends the window closes - configurable.

Setup

Optional user commands
The :FloatingTerminal* family, off if you prefer pure keymaps.
Generated keymaps
One config line binds the toggle key - or bind it yourself.
Starts in insert mode
start_in_insert drops you straight at the prompt.
Zero dependencies
Pure Lua, ships against Neovim 0.8+. Titles need 0.9+.

05Commands & Config

User Commands

Command	Description
:FloatingTerminalOpen	Open (or focus) the floating terminal window
:FloatingTerminalClose	Hide the window (buffer and shell sessions persist)
:FloatingTerminalToggle	Toggle open / close - bind this to your keymap
:FloatingTerminalResize	Recompute geometry and reposition the window
:FloatingTerminalNew [name]	Create a new named session (auto-named if no argument)
:FloatingTerminalCloseSession	Terminate the active session and remove its buffer
:FloatingTerminalNext	Switch to the next session in the tab bar
:FloatingTerminalPrev	Switch to the previous session in the tab bar
:FloatingTerminalSwitch {n}	Jump directly to session by index
:FloatingTerminalRename [name]	Rename the current session (prompts if no argument)

Configuration Options

Option	Type	Default	Description
width	number	0.8	Fraction of editor width
height	number	0.8	Fraction of editor height
border	string	"rounded"	Border style: single, double, rounded, solid, shadow
start_in_insert	bool	true	Enter insert mode when opening
create_user_command	bool	true	Register :FloatingTerminal* commands
create_keymap	bool	true	Register the toggle keymap
keymap	string	"<leader>tt"	Key to toggle the terminal
close_on_job_exit	bool	true	Auto-close window when shell exits
title	string	"Terminal"	Window title (Neovim 0.9+)
session_name_prefix	string	"Terminal"	Prefix for auto-generated session names
keymap_new	string	"<A-n>"	Create a new terminal session
keymap_close_session	string	"<A-x>"	Close the active session; "" or nil to disable
keymap_next	string	"<A-l>"	Switch to the next session
keymap_prev	string	"<A-h>"	Switch to the previous session
keymap_rename	string	"<A-r>"	Rename the current session interactively

06Screenshot

Floating terminal - centered, rounded border, reuses one buffer

~297

Lines of Lua

File

Dependencies

0.8+

Neovim req.

07Installation & Usage

Lua

{
  "lambertse/nvim-toggleterm",
  config = function()
    require("nvim-toggleterm").setup({
      width                = 0.8,
      height               = 0.8,
      border               = "rounded",
      start_in_insert      = true,
      create_user_command  = true,
      create_keymap        = true,
      keymap               = "<leader>tt",
      close_on_job_exit    = true,
      title                = "Terminal",
      -- multi-session
      session_name_prefix  = "Terminal",
      keymap_new           = "<A-n>",
      keymap_close_session = "<A-x>",
      keymap_next          = "<A-l>",
      keymap_prev          = "<A-h>",
      keymap_rename        = "<A-r>",
    })
  end,
}

With the default config, toggle the terminal with <leader>tt or via :FloatingTerminalToggle. The shell opens in insert mode. Exit to normal mode with Ctrl-\ Ctrl-n, then close or toggle the window. Press Alt-n to open a second session, Alt-l / Alt-h to navigate between them, and Alt-r to rename the active one. macOS users may need to configure Alt key forwarding in iTerm2 or Kitty.

08Future Work

✓

Multiple named terminals

Open a "test" terminal and a "server" terminal independently, each with their own buffer. Navigate via winbar tab bar or Alt keymaps.

○

Send-to-terminal API

Pipe lines or visual selections from a buffer into the floating terminal - without duplicating built-in Neovim features.

○

Status line integration

Show whether a terminal session is currently active in lualine or heirline.

✓

Buffer reuse

The shell session, history, and working directory persist across toggles.

✓

Auto-resize on VimResized

Window always stays proportional when the editor is resized.

✓

Zero dependencies

Pure Lua, one file, ships with Neovim 0.8+ - no extra setup.

One file. Multiple sessions.

Install it, bind <leader>tt, and never leave Neovim to open a terminal again. Spin up a second session with Alt-n, switch with Alt-l/h - all in one floating window.

View on GitHub

~/plugins/nvim-toggleterm

01The Problem: Leaving the Editor for a Terminal

02Why Write My Own Plugin?

03Design Principles

04Features

05Commands & Config

User Commands

Configuration Options

06Screenshot

07Installation & Usage

08Future Work

Pomodoro Timer

iBridge - IPC messaging & RPC framework

Vietnamese Card Board Scorer

Understanding MachO Binary Format

.css-1rtaf71{color:var(--ink-text-muted);}~/plugins/nvim-toggleterm

.css-1nm334o{font-family:var(--chakra-fonts-mono);font-size:12px;font-weight:700;color:var(--ink-sage-deep);margin-right:10px;vertical-align:3px;letter-spacing:.04em;}01The Problem: Leaving the Editor for a Terminal

02Why Write My Own Plugin?

03Design Principles

04Features

05Commands & Config

User Commands

Configuration Options

06Screenshot

07Installation & Usage

08Future Work

Pomodoro Timer

iBridge - IPC messaging & RPC framework

Vietnamese Card Board Scorer

Understanding MachO Binary Format

~/plugins/nvim-toggleterm

01The Problem: Leaving the Editor for a Terminal