From e5d4002b38c098ba7d2233f1670d7c23953ffaba Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Wed, 23 Sep 2026 04:55:11 +0100 Subject: [PATCH] docs: update instructions to enforce usage of auto-spawning headless neovim instance --- instructions.md | 2 +- nvim-core/src/instructions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/instructions.md b/instructions.md index b8612a6..f7d41b9 100644 --- a/instructions.md +++ b/instructions.md @@ -107,6 +107,6 @@ To maintain absolute traceability, we link memory items directly to the exact gi ## 15. Neovim Integration & God Mode -The project contains two MCP binaries (win-nvim and linux-nvim) that bridge JSON-RPC over stdio directly to the active Neovim instance (using `active_nvim.txt` for Last Focused Wins telemetry). +The project contains two MCP binaries (win-nvim and linux-nvim) that bridge JSON-RPC over stdio directly to the active Neovim instance (using `active_nvim.txt` for Last Focused Wins telemetry). If no interactive instance is open, they will automatically spawn and connect to a persistent headless Neovim background instance. - These binaries expose basic tools (`nvim_get_cursor`, `nvim_get_active_buffer`, `nvim_list_buffers`, etc.). - **God Mode**: They also expose `nvim_execute_lua`. This is the ultimate fallback tool. If you need to access *any* Neovim API that does not have a dedicated Rust tool (e.g., getting LSP diagnostics, evaluating a visual selection block based on modes, setting registers), you MUST write a short Lua script and pass it to `nvim_execute_lua`. Do not attempt to recompile the Rust server to add new basic tools; use the Lua escape hatch dynamically. diff --git a/nvim-core/src/instructions.md b/nvim-core/src/instructions.md index 54d541f..ff498e5 100644 --- a/nvim-core/src/instructions.md +++ b/nvim-core/src/instructions.md @@ -28,4 +28,4 @@ If you need to access *any* Neovim API that does not have a dedicated tool (e.g. 4. **Buffer Focus:** When making changes to a specific buffer, always ensure the active window is switched to that buffer, and optionally move the cursor so the human can see the change visually. ## 3. The "Unix is NOT King" Rule -When Neovim is running and you need to perform file read/writes or search and replace within an opened project, **prioritize Neovim tools over basic unix terminal utilities** (like `cat`, `grep`, `sed`, `awk`, or PowerShell equivalents). Use Neovim as your primary interface to the codebase. +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 spawn a persistent headless Neovim daemon in the background to execute your commands. Use Neovim as your primary AST-aware interface to the codebase at all times.