coq.nvim: Fast Neovim Completion with SQLite, Coroutines, and 9000+ Snippets

The Performance Architecture: Why coq.nvim Is Faster Than Pure Lua

The README leads with a performance claim and immediately backs it with specific mechanisms. Four design choices combine to make the completion pipeline faster than a pure Lua implementation.

First, native C in-memory B-trees handle the data structures for candidate storage and lookup, avoiding the overhead of Lua tables for high-frequency operations.

Second, SQLite VM interrupts allow the completion engine to abort in-progress database queries when a new keystroke arrives, rather than waiting for a query to complete before handling the next input event.

Third, a coroutine-based incremental and interruptible scheduler processes completion candidates in small steps between Neovim event loop ticks, which prevents any single completion request from blocking the editor.

Fourth, TCP-style flow control manages the rate at which results are sent from the completion engine to Neovim's UI, preventing the display layer from being overwhelmed. The README notes that detailed performance documentation is in docs/PERF.md and that real-time performance statistics are available in the editor via :COQ stats.

Installing coq.nvim with lazy.nvim or VimPlug

The plugin has three components: the main coq_nvim plugin, a coq.artifacts plugin that provides the snippet database, and coq.thirdparty for optional third-party sources. All three live on separate branches of the repository.

For lazy.nvim, the installation block in init.lua is:

{
  "neovim/nvim-lspconfig",
  lazy = false,
  dependencies = {
    { "ms-jpq/coq_nvim", branch = "coq" },
    { "ms-jpq/coq.artifacts", branch = "artifacts" },
    { 'ms-jpq/coq.thirdparty', branch = "3p" }
  },

For VimPlug:

Plug 'ms-jpq/coq_nvim', {'branch': 'coq'}
Plug 'ms-jpq/coq.artifacts', {'branch': 'artifacts'}
Plug 'ms-jpq/coq.thirdparty', {'branch': '3p'}

The README marks nvim-lspconfig as required for the Neovim native LSP integration. Installing the plugin without it will not break the editor, but LSP completions will not work. The coq.thirdparty branch needs to be configured separately; it provides additional built-in sources such as a shell REPL, the nvim Lua API, a scientific calculator using bc, and comment banners using figlet.

LSP Integration and the Two-Line Setup Change

The LSP source in coq.nvim supports incremental completion, client-side caching, multi-server completion for cases where two language servers (such as tailwind and cssls) provide completions simultaneously, and multi-encoding for utf-8, utf-16, and utf-32. It also handles header imports and LSP snippet grammar.

The README notes that two lines of change are required to enable LSP snippet support alongside an LSP server:

local coq = require "coq"
lsp.<server>.setup(coq.lsp_ensure_capabilities(<stuff...>))

For the new-style Neovim LSP configuration API:

vim.lsp.config(<server>, coq.lsp_ensure_capabilities(<stuff...>))
vim.lsp.enable(<server>)

Without this wrapper, snippet completions from LSP servers will not be resolved correctly. This is the most common configuration step that new users miss.

Fuzzy Search, Snippets, and the TreeSitter Source

coq.nvim uses a fuzzy matching algorithm that weights candidates by recency (recently inserted text ranks higher), proximity (text near the cursor ranks higher), and an ensemble of relative ranks and metrics described in docs/FUZZY.md. The README shows typo correction examples: `cour` matches `colour_space`, `flgr` matches `flag_group`, `nasp` matches `Namespace`.

The snippet database in coq.artifacts contains over 9,000 snippets compiled from multiple snippet sources. The README states that the compilation achieved 99 percent of LSP grammar coverage and 95 percent of Vim snippet grammar coverage, based on compiling 10,000 snippets. Custom snippets can be added with live preview using the documented SNIPS.md workflow.

The TreeSitter source shows completion context from the parse tree rather than just the surrounding text. The README notes a significant caveat: TreeSitter was still considered unstable in Neovim 0.5 at the time the documentation was written, with slow performance on large files. The source only parses a limited number of lines around the cursor and only on idle events specifically because of this performance limitation.

CTags, Paths, and Other Built-In Sources

The CTags source requires Universal CTags, not the older ctags package. The README is explicit about this distinction and includes the correct installation commands:

brew install universal-ctags
apt install universal-ctags

The old ctags binary will not work. Universal CTags compilation happens incrementally in the background so it does not block editing.

The Paths source completes file and directory paths relative to both the current working directory and the current file's location. It expands $VARIABLE and %WINDOWS_VARIABLE% references and previews file contents in the completion popup.

The Buffers source provides real-time completion from all open buffers, including files with thousands of lines, and stays non-blocking. The Registers source completes from named registers (a-z) and the yank register (0). The Tmux source completes from text visible in adjacent Tmux panes.

Where coq.nvim Is the Wrong Choice

coq.nvim has a concrete performance-versus-integration trade-off that matters for some users. The plugin has an opinionated design where all sources are unified in a single completion pipeline rather than assembled from independent plugins. Teams that need fine-grained per-source configuration, such as disabling completion for certain file types or giving different sources different priorities, need to check whether coq.nvim's configuration in docs/SOURCES.md and docs/CONF.md covers their use case.

The plugin requires Python 3.8 or later as a backend runtime alongside Lua. This is a dependency that plugins written entirely in Lua do not have. On systems where Python is not available or is tightly version-managed, this adds setup friction.

The alternative most commonly compared to coq.nvim in search data is nvim-cmp, which is a pure Lua completion framework that assembles sources from separate plugins. nvim-cmp is more configurable at the cost of requiring the user to choose and wire together each source. blink.cmp is a newer entrant in the same space. Neither is faster in the way coq.nvim claims to be, but both impose fewer runtime dependencies.

Maintenance Status and License

The last push to ms-jpq/coq_nvim was on 2026-09-22. The repository is not archived. There are no GitHub releases; versions are tracked through the coq branch directly.

The project is licensed under GPL-3.0. This is a strict copyleft license. Any plugin or tool that incorporates coq.nvim's source code must disclose its own source, state that it uses coq.nvim code, and carry the GPL-3.0 license. This affects plugin developers who want to wrap or extend coq.nvim in a closed-source or permissively licensed plugin.

Configuration documentation is split across several files in docs/: CONF.md for settings, KEYBIND.md for keybindings, SNIPS.md for custom snippets, DISPLAY.md for UI customization, SOURCES.md for source configuration, and STATS.md for the performance statistics display.

Editorial conclusion

coq.nvim is suited for Neovim users who find other completion plugins introduce perceptible lag, and for developers who want LSP, snippet, and TreeSitter completions from a single plugin rather than assembling separate sources manually. It is not suited for Vim users who need a plugin that works identically in both editors without Neovim-specific features, and it requires Python 3.8 or later alongside Lua, which adds a runtime dependency that simpler plugins do not have. The GPL-3.0 license imposes copyleft requirements on any plugin that incorporates coq.nvim's code. The last push was on 2026-09-22.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. ms-jpq/coq_nvim on GitHub
4. README