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.