riz/mcp-memory
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: strictly enforce agnostic Neovim rules and ban invisible shell edits

Browse Source
This commit is contained in:
Riz Ashraf committed 2026-10-08 23:29:44 +01:00
1 parent 5485b40d14
commit 003b3cb2bf
1 file changed
+25 -24
Download Patch File Download Diff File Expand all files Collapse all files
agent-rules/nvim_editing.md
+25 -24
View File
@@ -3,32 +3,33 @@ name: nvim_editing
description: Route code edits to Neovim buffers instead of disk/console when Neovim is running.
trigger: always_on
---
# Neovim Code Editing
# Neovim Code Editing (Agnostic & Universal)
## Never Spawn Headless Instances (CRITICAL)
**NEVER** run `nvim <filename>` via bash/terminal commands (`run_command`) to "open" or "show" a file to the user. Because agent terminal commands run in the background, this spawns an invisible ghost process.
These rules apply universally to ALL Neovim environments (Windows, WSL, or any remote server). Do not treat them as OS-specific.
If the user asks to "open", "show", or "see" a file in Neovim, you MUST use the `win-nvim` (Neovim) MCP Server to communicate with their *active* UI (e.g., using `nvim_execute_lua` with `vim.cmd('edit <file>')`).
## 1. No Invisible Shell Edits (CRITICAL)
**NEVER** use `sed`, `awk`, `python -c`, or `echo` to modify file contents from the terminal.
File edits must use EXACTLY one of two paths:
- **Active UI (Neovim MCP responsive):** Route edits through specialized MCP tools to provide live visual feedback.
- **No UI (Neovim MCP unresponsive):** Fall back to the built-in `replace_file_content` tool to generate clean chat diffs.
When making code edits or displaying search results/outputs:
1. Verify if the `win-nvim` (Neovim) MCP server is responsive.
2. If Neovim is running, apply code changes directly into the relevant Neovim buffers using nvim_execute_lua (e.g., using vim.api.nvim_buf_set_lines or vim.cmd).
3. DO NOT output large diffs or file contents to the chat console. Prefer live buffer manipulation over replace_file_content if the file is open in Neovim.
4. **Fallback Constraint (CRITICAL):** If Neovim is NOT running, you MUST use the `replace_file_content` tool to edit files. This ensures the user is presented with a visual diff block in the chat. **NEVER** use `sed`, `awk`, or `echo` to blindly modify file contents from the terminal.
## 2. Strict Tool Adherence (No Raw Lua RCE)
You must strictly use the specialized, sandboxed Neovim MCP tools:
- `nvim_buffer`: For reading, writing, saving, and creating scratch buffers.
- `nvim_window`: For creating splits and focusing panes.
- `nvim_visual`: For highlighting diffs, adding ghost text, and showing previews.
**DO NOT** use `nvim_execute_lua` to mutate editor state. It is restricted to **READ-ONLY** queries.
## Visual Cues & Auto-Save Policy (MANDATORY)
When manipulating buffers via Lua, you MUST provide visual feedback:
1. **Notifications:** Always trigger a notification explaining what you did using `require("notify")("Antigravity edited [File]: [Summary]", "info", { title = "Antigravity" })` (since `rcarriga/nvim-notify` and `noice.nvim` are installed).
2. **Buffer Focus:** Always switch the active Neovim window to the buffer you just edited (e.g., `vim.cmd('b ' .. bufnr)`).
3. **Cursor Jump:** Move the cursor to the line you edited (`vim.api.nvim_win_set_cursor(0, {line, 0})`).
4. **Auto-Save by Default:** You MUST save the buffer (`vim.cmd('write')`) after making edits so that external tools (tests, compilers, linters, git) can see the changes immediately and unattended tasks are not stalled.
5. **Interactive Review Mode (Exception):** The ONLY time you should disable auto-save (leaving the buffer modified and unsaved) is when you are actively halting execution to seek manual user confirmation for a highly sensitive change. This allows the user to visually review the `gitsigns` diff in the gutter before manually saving (`:w`).
## 3. Headless Quarantine
Headless mode (`nvim --headless`) is strictly banned for interactive edits.
**NEVER** run `nvim <filename>` via terminal commands to edit or "open" a file for the user (it spawns a zombie ghost process).
Headless instances are allowed ONLY for non-interactive background batch processing (e.g., project-wide formatting or linting).
## Interactive Review & Automatic Wakeup (MANDATORY)
When you modify a buffer and disable auto-save to allow the user to visually review the changes, you MUST NOT just wait idly for them to chat back.
You MUST spawn a background task to listen for their :w save event:
1. Use the ␍un_command tool to execute:
curl -s "http://127.0.0.1:3000/events/wait?topic=nvim:save:$((Get-Item $File).FullName.Replace('\', '/'))&session_id=$SessionId"
2. Set WaitMsBeforeAsync to a low value (e.g., 500ms) so it goes to the background immediately.
3. Stop calling tools and end your turn.
When the user saves the file, the curl command will complete and the system will automatically wake you up to proceed.
## 4. UI Presentation & Chat Console Minimization
Never output large plans, context blocks, or architectural discussions to the chat console if Neovim is running. You MUST use the `nvim_buffer` and `nvim_window` tools to open a vertical split (e.g., `Antigravity_Plan.md` scratch buffer) and present the markdown natively. Reserve the chat console strictly for brief confirmations.
## 5. Visual Cues & Auto-Save
When manipulating buffers via MCP:
1. **Focus & Jump:** Always switch the active Neovim window to the edited buffer and jump the cursor to the changed line.
2. **Auto-Save:** Auto-save the buffer by default so linters/compilers see it immediately.
3. **Interactive Review:** If pausing for human review (leaving unsaved), you MUST spawn a background `curl` task listening to `http://127.0.0.1:3000/events/wait?topic=nvim:save...` to wake you up when the user saves (`:w`).