2026/10/08
Neovim is a server: a tour of its architecture
- Your editor is two processes
- Everything speaks msgpack-RPC
- One thread, three queues
- Where your text lives
- Drawing without a screen
- Lua isnât a plugin, itâs half the editor
- Conclusions
I use Neovim every day, and for a long time I treated it as a black box with a Lua config bolted on. Then you write a plugin, typing starts to feel like typing over SSH from a train, and you have to actually learn how the thing is put together. Turns out âVim, but with Luaâ is selling it very short.
Neovim is a server. The thing you think of as âthe editorâ is one client among many, everything talks msgpack, one thread does all the editing, and the screen is just data. Letâs take it apart.
Everything on this page comes from Neovim master as of November 2026 (0.13-dev), either from the source tree or from an embedded
nvimI poked at over RPC. Function names, constants and messages are real, not vibes.
Your editor is two processes
Run nvim, then look at ps. Two processes. Since 0.10 the terminal UI lives in
its own process: the nvim you launched is a UI client that spawns
nvim --embed and talks to it over a pipe.
The server doesnât know what a terminal is. It owns buffers, windows, the Lua runtime and the event loop, and it describes the screen as grids of cells that it ships to whoever is attached. The TUI is one of those clients, on exactly the same footing as a GUI like Neovide, the VS Code extension, or a Python script holding a socket.
Pick a scenario and step through it:
Three things worth noticing. Everything, from keys to LSP messages to timers, enters through the same event loop. The TUI and a GUI take literally the same code path. And tree-sitter and the LSP client have no idea whether a change came from your fingers, a GUI or a plugin: they all funnel through the same place.
Everything speaks msgpack-RPC
The protocol between clients and server is msgpack-RPC, which is about as small as a protocol can get. Three message types, all plain arrays:
[0, msgid, method, params]: a request, expecting an answer[1, msgid, error, result]: the answer[2, method, params]: a notification, fire and forget
The API itself is generated. The build parses the C headers in src/nvim/api/,
generates the dispatch table and dumps metadata you can see with
nvim --api-info. Client libraries read that metadata to generate their own
bindings, so a new nvim_* function shows up everywhere at once.
The transport doesnât matter either. A channel can be stdio (--embed), a Unix
socket or named pipe (--listen), TCP, or a job started with
jobstart(cmd, { rpc = true }). Same unpacker, same dispatcher.
msgpack earns its keep here: for these messages itâs 25% to 70% smaller than the equivalent JSON, strings are length-prefixed so thereâs nothing to escape, and small integers fit in the type byte itself. That matters when every keystroke produces a message and every redraw produces a batch of them.
One thread, three queues
Hereâs the part that explains most laggy plugins. The editor core is
single-threaded. It sits on a libuv loop, and the
Loop struct in src/nvim/event/loop.h has three queues:
fast_events: processed right after eachuv_run(), whatever the editor is doingthread_events: how other threads hand work to the loop (viauv_async_send)events: the main queue, drained by the editor between commands
libuv callbacks (pipe reads, timers, signals, and any Lua you hang off
vim.uv) run whenever Neovim polls libuv. Thatâs not only when itâs idle
waiting for a key: long-running commands call os_breakcheck() to see if you
pressed Ctrl-C, and that polls too. So a fast callback can run in the middle of
basically anything, which is why it isnât allowed to touch editor state:
E5560: nvim_buf_set_lines must not be called in a fast event context
A handful of API functions are api-fast and run immediately: nvim_input
(it only appends to the typeahead buffer), nvim_get_mode, and a few more.
Everything else is deferred: queued on main_loop.events and executed in order
when itâs safe. vim.schedule() is just âput this on that queueâ.
Try it: type a few keys, then fire the 800 ms Lua call and keep typing. Keys
donât get lost, they just wait, because nothing polls libuv while Lua owns the
thread. Key latency becomes âhowever long that Lua call takesâ. A synchronous
loop over the whole buffer on every TextChanged does exactly this.
One correction to the docs while weâre here. :help api-fast says a deferred
request blocks while Neovim waits in an input() prompt. On current master
it doesnât: I sent nvim_buf_get_lines to an nvim --embed sitting in
input(), and later getchar(), and both times the answer came straight back.
What does block is the hit-enter / --More-- prompt, and thatâs exactly when
nvim_get_mode() reports blocking: true. GUIs poll it for that reason.
Where your text lives
Buffer text lives in the memline, which Neovim inherited from Vim
almost untouched. Itâs a B-tree of 4 KiB blocks (MEMFILE_PAGE_SIZE): pointer
blocks tagged pt in the source, and data blocks tagged da with lines
packed inside. Those blocks are pages of a memfile, which is backed by the swap
file. Thatâs the boring, battle-tested reason Vim-family editors open huge files
without flinching and recover your work after a crash: the swap file is the
bufferâs on-disk image.
On top of the text sit extmarks: positions that follow edits. Diagnostics,
tree-sitter highlights, virtual text, LSP inlay hints, git signs: all extmarks.
They live in the bufferâs marktree, a B-tree (MT_BRANCH_FACTOR = 10, so up
to 20 children per node) derived from klibâs kbtree and, per its own header,
inspired by Atomâs marker tree. Positions inside a node are stored relative to
their parent key, so moving that key moves its whole subtree for free, and an
edit that stays on one line stops looking as soon as it leaves that row.
Every change, whoever makes it, goes through one choke point that splices the
marktree and then tells the bufferâs listeners. There are two flavours:
on_bytes, byte-precise, used by tree-sitter; and on_lines, line-ranged, used
by the LSP client, which diffs the lines itself.
The gravity rules are the bit that makes this feel right. A mark with
right_gravity = true (the default) sits after text inserted at its position,
one with false stays before it. Diagnostic ranges default to a right-gravity
start and a left-gravity end (end_right_gravity = false), so typing at either
edge of undefined_var doesnât stretch the squiggle over your new text.
Also look at the column numbers once you edit after Ă© or the emoji. Neovim and
tree-sitter count UTF-8 bytes. LSP defaults to UTF-16 code units, a
Windows-and-JavaScript heirloom, so the client converts every position on the
way out (servers that support it can negotiate utf-8 instead).
Drawing without a screen
Redrawing is lazy. A change doesnât draw anything; it marks lines or windows as
needing it, with a severity (UPD_VALID = 10, UPD_SOME_VALID = 35,
UPD_NOT_VALID = 40, UPD_CLEAR = 50 in drawscreen.h). Right before Normal
mode blocks for the next key, update_screen() runs, win_update() redraws
the invalid rows into the grid, and the grid layer compares each new row with
whatâs already there.
Only the changed span goes out, as a grid_line event: a start column and a
list of cells, where each cell is [text], [text, hl_id] when the highlight
changes, or [text, hl_id, repeat] for runs. Scrolling becomes grid_scroll,
which literally means âcopy these cellsâ, plus the rows that scrolled in.
Below is a tiny modal editor wired to the same encoding. I checked the packing
against a real embedded nvim on the same edits (x, j, Ctrl-E, insert
mode) and the events match cell for cell, down to the odd-looking
[" ", 0, 0] Neovim appends when a line ends in spaces, so thereâs no doubt
about what to clear.
Some things to try: j sends no text at all, just a cursor move and the ruler
in the statusline. Ctrl-E is one grid_scroll plus one line. x at the start
of a long line resends the whole line, because every cell after it shifted.
The âfull repaintâ number is what youâd pay without any of this.
What I left out: floating windows and splits. A UI that opts into
ext_multigrid gets one grid per window and composes them itself. Everyone
else gets a single grid, composed server-side by ui_compositor.c, which is
why the TUI can draw floats without knowing floats exist.
Lua isnât a plugin, itâs half the editor
LuaJIT runs inside the server process, on the same thread as everything above.
vim.api.* are generated C bindings, so calling nvim_buf_set_extmark from Lua
is a C function call: no msgpack, no socket, no copy. Plugins get the exact API
a GUI gets, just without the wire.
And a lot of what feels like âcoreâ is Lua sitting on that API: the LSP client
(runtime/lua/vim/lsp/), the tree-sitter highlighter and its incremental
LanguageTree, vim.diagnostic, snippets, and the built-in vim.pack plugin
manager. The C core does text, the loop, the API and the screen; the
interesting features increasingly live one layer up, written against the same
interface you have.
Conclusions
Neovim is a single-threaded server with a tiny RPC protocol, a text store thatâs older than some of its contributors, a mark tree that keeps decorations glued to text, and a renderer that emits diffs instead of pixels. The TUI is just the client that ships in the box.
What that means in practice:
- Never touch the editor from a
vim.uvcallback. Parse there, thenvim.schedule(). Thatâs exactly what the built-in LSP client does. - Long Lua calls are input latency. Chunk the work across scheduled
callbacks, or move it out of process with
vim.system()and come back with the result. - Anything that speaks msgpack can drive Neovim.
nvim --listenplus a 20-line script gets you the same powers as a GUI, which is how Firenvim, the VS Code extension and every GUI out there work.
Next time something in your editor stutters, you know where to look: something is sitting on the one thread everyone has to share.