fredrikaverpil/neovim

Neovim RPC

When Claude Code runs inside a Neovim terminal, the $NVIM environment variable points to the parent Neovim's Unix socket. This gives full access to Neovim's msgpack-RPC API without any plugins or HTTP servers.

Prerequisites

Before sending any commands, verify the socket is available:

echo "$NVIM"

If $NVIM is empty, you are not running inside a Neovim terminal and cannot communicate with a Neovim instance.

Important: When NVIM_APPNAME is set, all nvim --server commands emit a Warning: Using NVIM_APPNAME=... message on stdout (not stderr). This corrupts parsed output (especially JSON). To suppress it, capture the output first, then filter:

result=$(nvim --server "$NVIM" --remote-expr 'EXPR') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Note: Piping nvim directly (e.g. nvim --server "$NVIM" ... | grep ...) can fail because $NVIM may not expand correctly in pipe contexts. Always use command substitution ($(...)) as shown above.

Evaluating expressions

All examples below use the command substitution pattern from Prerequisites to filter the NVIM_APPNAME warning. The shorthand nvimx EXPR means:

result=$(nvim --server "$NVIM" --remote-expr 'EXPR') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Use --remote-expr to evaluate a Vimscript expression and get the result back:

result=$(nvim --server "$NVIM" --remote-expr 'v:version') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

For Lua expressions, wrap them in luaeval():

result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.api.nvim_buf_get_name(0)")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

For multi-statement Lua that returns a value, use an IIFE:

result=$(nvim --server "$NVIM" --remote-expr 'luaeval("(function() local x = vim.api.nvim_get_current_win(); return vim.api.nvim_win_get_number(x) end)()")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Returning tables/lists

luaeval() returns Lua tables as Vimscript values. For complex data, encode as JSON:

result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.api.nvim_list_bufs())")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Sending commands

Use --remote-send to send keystrokes (as if the user typed them):

nvim --server "$NVIM" --remote-send ':echo "hello"<CR>'

Note: --remote-send does not return output and does not need the warning filter. Use --remote-expr when you need a return value.

Opening files remotely

Use --remote to open files in the running Neovim instance:

nvim --server "$NVIM" --remote file.txt

Use --remote-tab to open files in new tabs:

nvim --server "$NVIM" --remote-tab file1.txt file2.txt

Executing Lua without a return value

To run Lua that performs side effects (no return value needed):

result=$(nvim --server "$NVIM" --remote-expr 'execute("lua vim.notify(\"Hello from Claude\")")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

The execute() Vimscript function runs an Ex command and returns its output as a string (empty if the command produces no output).

Common patterns

# Current buffer path
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.api.nvim_buf_get_name(0)")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# List all buffer paths (JSON)
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.tbl_map(function(b) return vim.api.nvim_buf_get_name(b) end, vim.api.nvim_list_bufs()))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Current working directory
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.fn.getcwd()")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Current cursor position [row, col] (1-indexed row)
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.api.nvim_win_get_cursor(0))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Get a Neovim option value
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.o.filetype")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Check if an LSP client is attached
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.tbl_map(function(c) return c.name end, vim.lsp.get_clients({bufnr = 0})))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Reading help documentation

Do not use execute("help ...") — that opens help inside the editor as a side effect instead of returning content.

First, get the key paths via RPC (do this once per session):

# Neovim data directory (plugin install root is <data>/lazy/ for lazy.nvim)
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.fn.stdpath(\"data\")")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Built-in Neovim docs
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.fn.expand(\"$VIMRUNTIME\")")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Then use standard tools (fd, rg, Glob, Grep) to search and Read to view the files. Search <data>/lazy/*/doc/ for plugin docs and <runtime>/doc/ for built-in docs.

Search help tags (equivalent to :h query<Tab> completion):

result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.fn.getcompletion(\"MiniDiff\", \"help\"))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Finding plugin source code

Search runtime files (searches all runtime paths including user config, plugins, and pack/*/start/*):

# Find Lua source files matching a keyword (e.g. "codediff", "neotest")
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.api.nvim_get_runtime_file(\"lua/**/neotest*\", true))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Find any runtime file by pattern (plugin/, autoload/, syntax/, etc.)
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.api.nvim_get_runtime_file(\"**/neotest*\", true))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

Note: nvim_get_runtime_file only searches active runtime paths. Lazy-loaded plugins that haven't been loaded yet won't appear. See the lazy.nvim section below for how to find those.

Then use Read, Glob, or Grep to explore the returned paths.

lazy.nvim

The plugin manager lazy.nvim uses its own directory layout, separate from Neovim's built-in pack/ structure.

Plugin install directory

Plugins are installed under stdpath("data")/lazy/ (e.g. ~/.local/share/nvim-fredrik/lazy/<plugin-name>/). This path is not part of the standard Neovim packpath.

Finding plugins (loaded or not)

The lazy.nvim API knows about all plugins regardless of whether they are loaded:

# Get a specific plugin's directory
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("require(\"lazy.core.config\").plugins[\"neotest\"].dir")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# List all plugins with their paths (JSON)
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.json.encode(vim.tbl_map(function(p) return {name = p.name, dir = p.dir, dev = p.dev or false} end, vim.tbl_values(require(\"lazy.core.config\").plugins)))")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

You can also search the install directory directly with fd/Glob using the stdpath("data")/lazy/ path.

Dev plugins (dev = true)

Plugins with dev = true in their spec are loaded from a local development path instead of the install directory.

# Get the dev path from lazy.nvim config
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("require(\"lazy.core.config\").options.dev.path")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

# Check if a specific plugin is using dev mode
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("require(\"lazy.core.config\").plugins[\"codediff.nvim\"].dev")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

A dev plugin's source lives at <dev.path>/<plugin-name> (e.g. if dev.path is ~/code/public, then codediff.nvim with dev = true loads from ~/code/public/codediff.nvim). The plugin's .dir field in the lazy API already reflects this.

Plugin specs (lazy config files)

Plugin specifications (the Lua files that configure which plugins to load) live in the Neovim config directory, not in the install directory. Search there when you need to find how a plugin is configured:

# Find plugin spec files
result=$(nvim --server "$NVIM" --remote-expr 'luaeval("vim.fn.stdpath(\"config\")")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='
# Then use Glob/Grep to search the returned config path

Stale LSP diagnostics

When files are edited externally (e.g. by Claude Code tools), Neovim's LSP diagnostics can become stale — showing warnings for old line numbers or already-fixed issues. To refresh:

1. Reload the buffer and save — this forces the LSP to re-analyze:

result=$(nvim --server "$NVIM" --remote-expr 'execute("lua vim.api.nvim_buf_call(BUFNR, function() vim.cmd(\"edit! | write\") end)")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

2. Restart the LSP — if diagnostics are still stale after reloading:

result=$(nvim --server "$NVIM" --remote-expr 'execute("LspRestart")') && echo "$result" | grep -v '^Warning: Using NVIM_APPNAME='

After restarting, wait ~10 seconds for the LSP server to re-index before querying diagnostics again.

3. Verify independently — if diagnostics seem wrong, run the linter directly to confirm the actual state (e.g. golangci-lint run ./... for Go).

Safety

• Never send :q, :qa, :bdelete, or other destructive commands without explicit user confirmation.
• Never modify buffer contents via RPC without asking first — the user may have unsaved work or an undo history they care about.
• Prefer --remote-expr (read-only queries) over --remote-send (simulates typing) whenever possible.
• Always use command substitution + grep -v to suppress the NVIM_APPNAME warning (see Prerequisites).

Workflows

For common Neovim workflows (LSP interaction, debugging, plugin management), see the references/ directory.