Show HN: Vim Navigator – MCP server that lets AI agents drive your Neovim

An MCP server that lets AI agents drive a Neovim instance. The agent opens files, highlights code, adds annotations, folds sections, and splits views — turning Vim into a shared visual workspace for code walkthroughs, reviews, and pair programming.

How it works

You (in Vim) ←──────→ Neovim (--listen socket) ←──────→ MCP Server ←──────→ AI Agent  watching (pynvim) (Claude, etc.)

You (in Vim) ←──────→ Neovim (--listen socket) ←──────→ MCP Server ←──────→ AI Agent  watching (pynvim) (Claude, etc.)

The user keeps a Neovim window visible. The AI agent connects to it through the MCP server and manipulates the editor in real time — opening files, pointing at code, annotating lines, and building up layered explanations visually.

Requirements

• Neovim >= 0.9

• Python >= 3.10

• An MCP-compatible AI client (e.g. Claude Code)

Setup

1. Install

git clone https://github.com/krishnacaldas/vim-navigator.git cd vim-navigator python3 -m venv .venv source .venv/bin/activate pip install -e .

git clone https://github.com/krishnacaldas/vim-navigator.git cd vim-navigator python3 -m venv .venv source .venv/bin/activate pip install -e .

2. Start Neovim

In a terminal you can see:

./start-nvim.sh

Or manually:

nvim --listen /tmp/nvim-navigator.sock

3. Register with your AI client

Claude Code (CLI)

claude mcp add vim-navigator -- /path/to/vim-navigator/.venv/bin/python -m vim_navigator.server

Claude Code (settings.json)

{  "mcpServers": {  "vim-navigator": {  "command": "/path/to/vim-navigator/.venv/bin/python",  "args": ["-m", "vim_navigator.server"],  "env": {  "NVIM_SOCKET": "/tmp/nvim-navigator.sock"  }  }  } }

{  "mcpServers": {  "vim-navigator": {  "command": "/path/to/vim-navigator/.venv/bin/python",  "args": ["-m", "vim_navigator.server"],  "env": {  "NVIM_SOCKET": "/tmp/nvim-navigator.sock"  }  }  } }

4. Use it

Ask your AI agent to walk you through code, explain a module, or review changes. It will drive your Vim window in real time.

Tools

Tool Description

open_file Open a file and jump to a line

goto_line Jump to a line in the current buffer

highlight_lines Highlight a range of lines with an optional label

annotate Add virtual text annotation at end of a line

fold_range Collapse a range of lines

unfold_all Expand all folds

clear Remove all highlights and annotations

close_splits Close all splits, keep current window

split_open Open a file in a vertical/horizontal split

get_context Get current file, cursor position, visible range

vim_command Run any Vim ex command (escape hatch)

Configuration

Environment Variable Default Description

NVIM_SOCKET /tmp/nvim-navigator.sock Path to the Neovim socket

Example session

You: "Walk me through the auth flow"

Agent: opens auth/handler.go at line 45 highlights lines 45-62, labels "entry point" annotates line 51: "JWT validated here" splits open auth/middleware.go at line 20 "Left side is the handler, right side is the middleware that runs before it. The JWT check on line 51 uses the same validator as the middleware on line 23..."`

Walkthrough mode

For the best experience, ask the agent to "walk you through" something — a PR, a feature, a bug. The agent will:

• Break the topic into logical layers

• Open each file, highlight and annotate the key parts

• Give a brief explanation of what you're seeing

• Pause and ask you a question before moving on

This turns code review from reading diffs into an interactive, guided session. You see the code in your editor while the agent explains it step by step.

See AGENTS.md for the full walkthrough protocol and best practices.

License

MIT