Connect to a running Neovim instance over its Unix socket or TCP address.

Call this before any other tool if the agent is not yet connected. Connection is persistent for the session; you only need to call it once unless you want to switch instances.

Called with no arguments: auto-connects when exactly one instance is running; returns a list of instances when multiple are found.

Optional selection (provide at most one):

• index: pick from the listed instances (1-based).

• socket_path: connect directly to a known Unix socket or host:port.

• terminal_pid: find the Neovim instance whose process tree contains this PID (useful when Neovim runs inside a specific terminal).

Returns {connected, cwd, file} on success, or {error} with details on failure (e.g. no instances found, connection timeout, bad index).

Run one or more Vim ex commands in Neovim. This is a mutation tool — commands can modify buffers, files on disk, windows, and editor state.

command: a single command string or a list of strings, without the leading ':'. E.g. "w", "e src/main.py", "42", "wincmd v", "lua vim.print(...)", or ["wincmd p", "e file.py", "wincmd p"].

Use this for editor operations that don't have a dedicated tool (e.g. saving, opening files, splitting windows, setting options). Use send_keys instead when you need normal-mode motions or operator sequences. Use find_and_replace_buf or write_full_buf for buffer text edits — they are safer and provide undo.

Returns {output} with the command's captured output, or {error} if the command failed. When given a list, returns a list of results in the same order; execution stops on the first error.

Send raw keystrokes to Neovim as if typed by the user. This is a mutation tool — keystrokes can modify buffers, change mode, and trigger editor actions.

keys: a string of Vim keystrokes. Esc is prepended automatically, so input always begins in normal mode. Multi-mode sequences must be sent in a single call (e.g. "17GVG", not "17GV" then "G"). Use Vim notation for special keys (e.g. "", "v", "").

Use this for normal-mode motions, visual selections, or operator sequences. Use send_command for ex commands, and find_and_replace_buf or write_full_buf for text edits — they are safer and provide structured results.

Returns {sent} confirming the keys that were dispatched. Keystrokes are fire-and-forget; errors from the resulting Vim actions are not captured in the return value.

Get LSP diagnostics from all open buffers in Neovim. Read-only.

Use this for a project-wide overview of errors and warnings. Use get_buf_diagnostics instead when you only need diagnostics for a specific file — it is more focused and returns less data.

Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when there are no diagnostics. Results depend on which LSP servers are attached and which buffers are loaded in Neovim.

Get LSP diagnostics for a single Neovim buffer. Read-only.

file: path relative to Neovim's cwd (as shown in get_state buffers). The buffer must already be open in Neovim; returns an error otherwise.

Use this when you need diagnostics for one specific file. Use get_all_diagnostics instead for a project-wide overview.

Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when the buffer has no diagnostics.

Find and replace text in a Neovim buffer. The edit happens in-memory and is fully undoable — nothing is written to disk until the user saves.

file: path relative to Neovim's cwd (as shown in get_state buffers). old_string: the exact text to find. Must match exactly once in the buffer; returns an error if not found or if it matches multiple locations. Include surrounding lines to disambiguate. new_string: the replacement text.

Creates the buffer if it doesn't already exist. Use this for targeted edits. Use write_full_buf instead when replacing the entire buffer content. Use read_full_buf or read_buf_range first if you need to see the current content before editing.

Returns {start_line, lines_removed, lines_added, total_lines} on success, or {error} with a message on failure.

Replace the entire content of a Neovim buffer. The edit happens in-memory and is fully undoable — nothing is written to disk until the user saves.

file: path relative to Neovim's cwd (as shown in get_state buffers). content: the full new text for the buffer.

Creates the buffer if it doesn't already exist. Use this when you need to rewrite the whole file. Use find_and_replace_buf instead for targeted edits that preserve surrounding content.

Returns {total_lines} with the new line count.

Read the full content of a Neovim buffer. Read-only; reads from Neovim's in-memory buffer, which may differ from the file on disk if there are unsaved changes.

file: path relative to Neovim's cwd (as shown in get_state buffers). The buffer must already be open in Neovim; returns an error otherwise.

Use this when you need to see the entire file. Use read_buf_range instead when you only need a specific section — it returns less data.

Returns {lines, total_lines}. lines is a list of strings, each prefixed with its 1-based line number (e.g. "1: first line").

Read a specific line range from a Neovim buffer. Read-only; reads from Neovim's in-memory buffer, which may differ from the file on disk if there are unsaved changes.

file: path relative to Neovim's cwd (as shown in get_state buffers). The buffer must already be open in Neovim; returns an error otherwise. start_line: first line to read (1-indexed, inclusive). end_line: last line to read (1-indexed, inclusive). Out-of-range values are clamped to the buffer bounds. If start_line > end_line they are swapped automatically.

Use this when you only need a section of a file. Use read_full_buf instead when you need the entire buffer.

Returns {lines, total_lines}. lines is a list of strings, each prefixed with its 1-based line number (e.g. "10: some code").

Full snapshot of the current Neovim session. Read-only — does not modify any editor state.

Use get_state_brief for quick orientation at the start of a turn. Use this when you need the complete picture: all window details, folds, marks, diagnostics summaries, highlights, and indent settings.

Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative paths of all listed buffers), modified_buffers, current_tab, tab_count.

windows — list of visible windows (current tab only). The active window is always first, the alternate window (previous) is second. Each window entry contains: file (path relative to cwd), filetype, total_lines, modified, buftype ("file" for normal buffers, "terminal", etc.), line, col, indent: {expandtab, shiftwidth, tabstop}. Optional per-window fields (present when applicable):

• role: "active" or "alternate".

• context: numbered lines surrounding the cursor.

• selection: {start_line, start_col, end_line, end_col} in visual modes.

• folds: list of [start, end] closed fold ranges.

• diagnostics_summary: {error, warning, info, hint} counts.

• marks: list of {mark, line, col} for lowercase (a-z) buffer marks.

• mcp_highlights: list of {start_line, end_line, color} for active highlights.

Lightweight snapshot of the Neovim session for quick orientation. Read-only — does not modify any editor state.

Use this at the start of each turn to see what the user is working on. Use get_state instead when you need the full picture: all windows, folds, marks, diagnostics summaries, highlights, and indent settings.

Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative paths of all listed buffers), modified_buffers, and active_window: {file, filetype, total_lines, modified, buftype, line, col, context}. context is a short list of numbered lines around the cursor.

If an alternate window exists, also returns alternate_window with the same fields.

Add a colored line highlight to a Neovim buffer. This is a visual annotation only — it does not modify buffer content and is not persisted to disk. Highlights stack; calling this multiple times adds more highlights without removing previous ones.

file: path relative to Neovim's cwd (as shown in get_state buffers). The buffer must already be open in Neovim; returns an error otherwise. start_line: first line to highlight (1-indexed, inclusive). end_line: last line to highlight (1-indexed, inclusive). Out-of-range values are clamped. If start_line > end_line they are swapped. color: any hex color (e.g. "#3b4048") or Neovim color name (e.g. "DarkGreen"). Defaults to "#3b4048".

Use this for a single highlight. Use highlight_ranges to apply multiple highlights in one call. Use clear_highlights to remove all highlights from a buffer.

Returns {highlighted} with the number of lines highlighted.

Add colored line highlights to one or more Neovim buffers in a single call. This is a visual annotation only — it does not modify buffer content and is not persisted to disk. Highlights stack; calling this adds more highlights without removing previous ones.

highlights: a list of dicts. Each dict requires:

• file: path relative to Neovim's cwd (as shown in get_state). The buffer must be open in Neovim.

• start_line: first line (1-indexed, inclusive).

• end_line: last line (1-indexed, inclusive).

• color (optional): hex color or Neovim color name. Defaults to "#3b4048". Out-of-range lines are clamped.

Use this when you need to highlight several ranges at once (possibly across different files). Use highlight_range for a single range. Use clear_highlights to remove all highlights from a buffer.

Returns a list of {highlighted} results in the same order as the input. Raises an error if any item is missing required keys.

Example: [{"file": "foo.py", "start_line": 1, "end_line": 3, "color": "#5f3a3a"}, {"file": "foo.py", "start_line": 10, "end_line": 12}]

Remove all MCP highlights from a Neovim buffer. Only removes highlights added by highlight_range or highlight_ranges — does not affect syntax highlighting, LSP highlights, or other plugins. Does not modify buffer content. Safe to call even if no highlights are present (returns {cleared: true} either way).

file: path relative to Neovim's cwd (as shown in get_state buffers). The buffer must already be open in Neovim; returns an error otherwise.

Use this to clean up highlights after an annotation workflow. Use highlight_range or highlight_ranges to add highlights.