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. "<CR>", "<C-w>v", "<Tab>").
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.
Type text into a terminal buffer's running program (usually a shell)
by writing to its job channel. This is a mutation tool — the text
reaches the program's stdin as if typed, but is not executed unless
submit is true.
text: the text to send, raw. In most shells an embedded newline acts
like pressing Enter, so multi-line text may execute line by line.
When submit is false, trailing newlines are stripped so nothing
runs by accident.
terminal: which terminal to target — a buffer number or buffer name,
as listed under `terminals` in `get_state` / `get_state_brief`.
Names match exactly first, then by unique substring. Omit it when
exactly one terminal exists; with several open, omitting it
returns an error listing them.
submit: false (default) leaves the text at the prompt for the user
to review and press Enter. true appends a carriage return so the
program executes it immediately. NEVER pass submit=true unless
the user has explicitly asked for the command to be run — "put",
"paste", "type", or "prepare" a command always means
submit=false. Suggesting a command yourself is not permission to
run it. When in doubt, use submit=false and let the user press
Enter.
Use this whenever text needs to go into a terminal. It works
regardless of focus, mode, or visibility and never moves the user's
cursor — unlike `send_keys`, which requires focusing the terminal
and juggling modes. Terminal buffers cannot be edited with the
buffer tools.
Returns {sent, terminal, buf, submitted} on success — sent is the
byte count actually written. On failure returns {error}, including
a `terminals` list when the target was missing or ambiguous.
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, virtual text, and
indent settings.
Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative
paths of all listed buffers), modified_buffers, current_tab, tab_count,
and terminals — a list of open terminal buffers as {buf, name,
visible}, present only when at least one exists (targets for
`send_to_terminal`).
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.
- mcp_virtual_text: list of {line, position, lines, color} for active virtual text.
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, virtual
text, 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. When terminal buffers exist, returns terminals — a
list of {buf, name, visible} (targets for `send_to_terminal`).
+6 more tools listed on main page