2026/10/08

Share

on:

Neovim is a server: a tour of its architecture

share

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 nvim I 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:

Follow a message through NeovimPick a scenario and step through it. Every hop names the real function or message involved.
Clients
TUInvim, as a UI client
GUIany msgpack-RPC UI
Scriptspynvim, nvim --server
nvim --embed (the server)
Channelsmsgpack_rpc/channel.c
Event looplibuv + multiqueues
LuaLuaJIT, vim.*
APInvim_* in api/*.c
Editor statenormal.c, edit.c, ex_docmd.c
Buffermemline + marktree
Tree-sitterincremental parser
Redrawdrawscreen.c, grids
Child processes
LSP serverchild process, JSON-RPC
:terminal jobpty + libvterm

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-RPC on the wireReal encodings, byte for byte what Neovim's packer produces. Hover a byte or a value to see what it means.

Hover a byte.
msgpack
Same thing as JSON
Saved

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 each uv_run(), whatever the editor is doing
  • thread_events: how other threads hand work to the loop (via uv_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”.

One thread, three queuesA model of Neovim's main loop. Fire events at it, then try blocking it with a slow Lua call or a hit-enter prompt.
libuvready I/O, timers
typeaheadkeys for the editor
main_loop.eventsdeferred work
Main threadidle, waiting in uv_run()
    IdleFast callbackHandling a keyDeferred eventLua hogging the threadPrompt up
    Last key latency–
    Worst key latency–
    Queued right now0

    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.

    Edit the buffer, watch everyone reactThe textarea stands in for a buffer. Each edit becomes one splice: extmarks move by Neovim's gravity rules, and the same change is handed to tree-sitter and the LSP client in their own units.
    Try typing right before café on line 3, or deleting across undefined_var.
    What gets drawn (extmarks applied)
    diagnostic rangeright_gravity = trueright_gravity = false
    nvim_buf_attach on_bytes
    Tree-sitter: tree:edit()LSP: didChange contentChanges

    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.

    A tiny Neovim, and what it sends to the UIClick the editor and use it: h j k l, i a o, x, dd, Esc, Ctrl-E / Ctrl-Y to scroll. Every keypress shows the redraw batch a real UI would receive.
    0 Normal1 Comment2 Keyword3 String4 Number5 Function6 EndOfBuffer7 StatusLine8 ModeMsg
    Last keyattach
    Cells sent
    Bytes on the wire
    Full repaint would be
    ["redraw", 
] batch for that key

    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.uv callback. Parse there, then vim.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 --listen plus 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.