Neovim interaction skill

This skill provides comprehensive knowledge for interacting with Neovim in this environment.

Architecture

Binary management

• Nvim binary installed to ~/.local/share/nvim/<version>-<sha>/bin/nvim
• Symlinked from ~/.local/bin/nvim (managed by home 3p)
• Custom nvim builds with bundled plugins available via .github/workflows/build-nvim.yml

Configuration structure

• Entry point: .config/nvim/init.lua (sets up lua paths)
• Plugin configs: .config/nvim/plugin/ (modular lua files)
  • editing.lua, git.lua, grep.lua, interface.lua, lsp.lua, mini.lua
  • system.lua, tab.lua, terminal.lua, treesitter.lua, window.lua
• Treesitter queries: .config/nvim/queries/

Configuration guidelines

• Prefer Lua for all Neovim configuration
• Use modular approach: separate files in .config/nvim/plugin/ for different features
• Use <Space> instead of <leader> for keybindings
• Generally avoid plugins; prefer minimal, native configurations

Native package manager (vim.pack)

Install plugins using vim.pack.add() in plugin config files (nvim 0.12+):

vim.pack.add({
  { src = "https://github.com/user/plugin" },
})

Key details:

• Plugins stored in $XDG_DATA_HOME/nvim/site/pack/core/opt
• Optional version constraints: version = vim.version.range("1.0.0")
• Check if loaded: local ok, plugin = pcall(require, "plugin-name")

Example from mini.lua:

vim.pack.add({
  { src = "https://github.com/nvim-mini/mini.nvim" },
})

local ok_bufremove, _ = pcall(require, "mini.bufremove")
if ok_bufremove then
  require("mini.bufremove").setup()
end

Building custom nvim releases

The repository includes infrastructure to build nvim nightly with bundled plugins:

Build system components

• scripts/build-nvim.lua: lua script that downloads nvim nightly, bundles plugins, and creates tarballs
• .config/nvim/nvim-pack-lock.json: lock file defining plugin versions
• .github/workflows/build-nvim.yml: workflow to build for darwin-arm64, linux-arm64, linux-x64
• requires luajit with dkjson (via .config/setup/luajit bootstrap)

Lock file format

{
  "plugins": {
    "plugin-name": {
      "src": "https://github.com/user/plugin",
      "rev": "commit-hash-or-tag"
    }
  }
}

Build process

1. Downloads nvim nightly from neovim/neovim releases
2. Clones each plugin from lock file at specified revision
3. Installs plugins to share/nvim/site/pack/core/opt/
4. Generates helptags with nvim --headless +'helptags ALL' +qa
5. Creates reproducible tarball with checksums
6. Verifies plugins load correctly

Running the build

# Locally (requires luajit with dkjson)
bash scripts/build-nvim

# Via GitHub workflow
gh workflow run build-nvim.yml -f create_release=false  # test build
gh workflow run build-nvim.yml -f release_tag=2025.11.23  # create release

Nvim wrapper and daemon management

The nvim wrapper at ~/.local/bin/nvim provides automatic server management with flexible socket configuration.

Socket configuration

• Default socket: ~/.config/nvim/nvim.sock
• Specify via CLI: nvim --server /path/to/socket.sock (uses nvim's native flag)
• Specify via environment: NVIM_SOCKET=/path/to/socket.sock nvim
• Priority: --server flag > NVIM_SOCKET env var > default

Client mode (nvim)

Automatically starts a daemon server if not running, then connects:

nvim file.txt                                    # uses default socket, auto-starts if needed
nvim --server /tmp/project.sock file.txt        # uses custom socket
nvim --remote-expr "execute('echo 42')"          # remote commands work too

Daemon management (nvimd)

Explicit daemon control commands:

nvimd start                                      # start server at default socket
nvimd --server /tmp/project.sock start           # start at custom socket
nvimd stop                                       # stop server
nvimd status                                     # check if running

Multiple servers

Each socket path gets its own daemon, pidfile, and logfile:

• Socket: /path/to/foo.sock
• Pidfile: /path/to/foo.pid
• Logfile: /path/to/foo.log

Reloading configuration

To reload nvim configuration after making changes:

nvim --remote-expr "execute('source ~/.config/nvim/init.lua')"
# or with custom socket:
nvim --server /tmp/project.sock --remote-expr "execute('source ~/.config/nvim/init.lua')"

This sources the configuration in running nvim instances without restarting them.