Antigravity Neovim MCP Instructions

When connected to this Neovim MCP server (win-nvim), you have powerful tools to interact directly with the active Neovim editor.

The Consolidated Tool Arsenal (v3)

The server consolidates granular Neovim operations into 5 smart mega-tools:

nvim_buffer: Buffer and file management. Actions: read, replace, save, undo, redo, create_scratch.
nvim_workspace: Window split and focus management. Actions: list_buffers, list_windows, focus, split, cwd.
nvim_intelligence: Code intelligence and LSP. Actions: hover, definition, references, outline, query, diagnostics, rename, code_action.
nvim_ui: Visual highlighting, diff previews, and ghost text. Actions: highlight, ghost_text, clear.
nvim_exec: Escape hatch for raw evaluation. Actions: lua, vimscript, terminal.

1. Using Consolidated Domain Tools First

Always prefer the specific consolidated tools (like nvim_buffer, nvim_workspace, nvim_ui, etc.) over writing raw Lua scripts. These tools are strongly typed, tested, and safe.

2. Lua God Mode (`nvim_exec` with action `lua`)

If you need to access any Neovim API that does not have a dedicated tool (e.g., changing options, setting autocmds), you MUST use nvim_exec with action lua as your escape hatch. CRITICAL: nvim_exec is restricted to READ-ONLY queries. Do NOT use it to mutate editor state.

CRITICAL RULES for `nvim_exec` (`lua`):

Never Block: Never use interactive prompt functions or interactive confirmation flags in substitutions (e.g., %s/old/new/gc). This will cause the headless MCP bridge to deadlock forever.
Visual Feedback: Always trigger a notification using require("notify")("Antigravity: [Action]", "info", { title = "Antigravity" }).
Auto-Save: If you modify a file buffer, always save it using vim.cmd('write') within the same Lua script so external tools can see the changes, unless you explicitly want to pause for manual human review.
Buffer Focus & Centering: When making changes to a buffer, switch the active window to that buffer, jump to the edited line/column (vim.api.nvim_win_set_cursor(0, {line, col})), and center the viewport horizontally and vertically (vim.cmd('normal! zz'); vim.cmd('normal! ' .. col .. '|zs')) so the user immediately sees the change in full context.

3. The "Unix is NOT King" Rule

You should ALWAYS prioritize Neovim tools over basic unix terminal utilities (like cat, grep, sed, awk, or PowerShell equivalents) for file read/writes and search/replace. If an interactive Neovim session is not currently open, the server will automatically connect or spawn a persistent headless Neovim daemon in the background to execute your commands.

CRITICAL PAIR-PROGRAMMING EXCEPTION: While the headless background instance is great for autonomous, routine tasks, if you are performing collaborative "pair programming" activities, complex refactors that require visual engagement, or step-by-step human review, DO NOT execute them blindly in the background. Instead, explicitly ask the user to open a Neovim UI first so they can visually follow along. Use Neovim as your primary AST-aware interface to the codebase at all times.

4. Tool Schema Discovery

Do NOT grep or search the Rust source code to find tool schemas or arguments. All lazy-loaded MCP tool schemas are automatically cached as JSON files on your disk. To understand a tool's arguments, directly read ~/.gemini/antigravity-cli/mcp/win-nvim/<tool_name>.json (or linux-nvim).

3.5 KiB Raw Blame History