Nvr

NVR -- Neovim Remote Integration

Neovim remote integration for Claude Code. Automatically discovers the correct neovim instance based on working directory and git root, then opens files, checks status, or lists instances.

Current Workspace (Auto-Captured)

Working Directory: !pwd Discovered Socket: !timeout 3 nvr-discover 2>/dev/null || echo "None" Active Instances: !timeout 2 nvr --serverlist 2>/dev/null | wc -l neovim process(es) Instance List: !timeout 3 nvr-list 2>/dev/null || echo "None"

First Step

When invoked with no arguments, the FIRST action must be a single AskUserQuestion tool call (no preamble). Use this EXACT string for the question field:

"What would you like to do with nvr?"

Set header: "Action" and offer these options:

• open -- Open a file in neovim at an optional line number
• list -- List all active neovim instances
• status -- Show current neovim instance details
• workspace -- Show workspace context (git, neovim, cwd)
• help -- Show subcommand grammar and usage

If the user's message already includes a subcommand (e.g. /nvr open README.md 42), skip the AUQ and jump straight into the matching workflow. See "Subcommand Grammar" below.

Helper Commands

All real work is done by the executables in the plugin's bin/ directory. Claude Code puts that directory on PATH automatically, so invoke them as bare commands -- no path construction, no $CLAUDE_PLUGIN_ROOT. ($CLAUDE_PLUGIN_ROOT is not available inside skills -- neither substituted nor set as an env var; see anthropics/claude-code#9354, #44057.)

• nvr-open <file> [line] -- open file at optional line in discovered instance
• nvr-list -- list all active neovim instances with directories
• nvr-status -- show PID, cwd, buffer count for current instance
• nvr-workspace -- show git root, branch, neovim instance for cwd
• nvr-discover [dir] -- discover socket for a directory (used internally)

Do NOT construct paths to scripts. Use the bare commands above.

Auto-Invocation

This skill should be automatically invoked whenever opening files in the user's editor. When using tools like Read or Grep and the user asks to "open that file" or "show me that in neovim", invoke nvr-open with the file path.

Subcommand Grammar

/nvr                              -> AUQ menu (interactive)
/nvr open <file> [line]           -> open file at optional line
/nvr list                         -> list all neovim instances
/nvr status                       -> current instance details
/nvr workspace                    -> workspace context
/nvr help                         -> usage reference

Workflow: OPEN

1. If the user supplied a file path, call nvr-open <file> [line] directly.
2. If no file was supplied, AUQ: header: "File", question: "Which file should I open?" -- accept free-text.
3. Parse natural language for file path and line number:
   • "database.py at line 45" -> nvr-open database.py 45
   • "src/utils/helper.py" -> nvr-open src/utils/helper.py
   • "the error on line 23 of server.js" -> nvr-open server.js 23
4. Show the command's output (success: socket path and file opened; failure: diagnostic info).

If the socket discovery fails, show the error and suggest running /nvr list to see available instances or setting $NVIM_SOCKET manually.

Workflow: LIST

Run nvr-list and show its output. Takes no arguments. The command queries all active sockets and displays each with its PID, working directory, and socket path.

If no instances are found, suggest starting neovim with nvim.

Workflow: STATUS

Run nvr-status and show its output. Takes no arguments. The command discovers the socket for the current directory, then queries neovim for PID, working directory, and buffer count.

If no matching instance is found, suggest running /nvr list to see what's available.

Workflow: WORKSPACE

Run nvr-workspace and show its output. Takes no arguments. The command gathers:

• Current working directory
• Git root and current branch (if in a git repo)
• Discovered neovim instance (if any)

Useful for debugging socket discovery or understanding project context.

Workflow: HELP

Print the subcommand grammar block from above, the helper commands list, and 2-3 usage examples. Do NOT call any helper script.

Examples:

/nvr open src/main.py 42          # Open file at line 42
/nvr list                         # Show all neovim instances
/nvr status                       # Current instance details
/nvr workspace                    # Git + neovim context

Socket Discovery

The nvr-discover utility finds the correct neovim instance for a directory using a two-pass strategy:

1. Git root match (preferred): Query each neovim instance for its git root. Pick the instance whose git root is the longest prefix of the target directory. This is immune to :lcd changes from autocmds.

2. Closest parent cwd match (fallback): If no git root match, fall back to getcwd() matching. Pick the instance whose working directory is the longest prefix of the target directory.

3. Environment override: Setting $NVIM_SOCKET to a socket path bypasses all discovery and uses that socket directly.

Important Notes

• The plugin requires nvr (neovim-remote) on PATH. Install with pip install neovim-remote.
• Socket discovery uses git root matching first, making it robust against :lcd changes from plugins like cmp-pandoc-references.
• When multiple instances match, the one with the longest (most specific) path wins.
• All workflows are CWD-dependent -- they use the current working directory for socket discovery.