> ## Documentation Index > Fetch the complete documentation index at: https://vietbui.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Neovim AI Operator Workflow > Neovim is not just an editor in this workflow. It is the human operator cockpit for code inspection, small corrective edits, LSP/DAP-backed understanding, an… # Neovim AI Operator Workflow Neovim is not just an editor in this workflow. It is the human operator cockpit for code inspection, small corrective edits, LSP/DAP-backed understanding, and live review of agent-generated changes. Agents should run as separate workers. Neovim should stay the human-facing IDE layer that can inspect, correct, debug, and send precise context back to agents. *** ## Core Thesis The best Neovim + AI setup is not "replace Neovim with a chat sidebar". It is: ``` AI agent changes code in repo/worktree -> Neovim auto-reloads changed buffers and diff views -> human reviews with LSP/DAP/diffview -> human makes small edits directly when faster -> human sends precise file/path/selection context back to agent -> Commandr/DiffViewer record approvals/evidence/task lifecycle ``` This preserves the reason to use Neovim: fast navigation, text objects, LSP intelligence, debugger integration, and direct editing muscle memory. *** ## Tool Roles | Tool | Role | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Neovim | Human operator IDE: inspect, modify, debug, review. | | Mason | Installs/manages LSP servers, DAP servers, linters, formatters in Neovim data dir. | | nvim-lspconfig | Attaches project language servers to buffers. | | nvim-dap | Debug Adapter Protocol client; launches/attaches debuggers. | | mason-nvim-dap | Bridges Mason-installed debug adapters into nvim-dap. | | diffview\.nvim | Local review surface for editing inside diffs. | | CodeCompanion.nvim | Neovim-native AI chat/workflow layer; supports ACP, MCP, agents such as Claude Code/Codex/OpenCode, editor context, tools, workflows, and rules files. | | Avante.nvim | Cursor-like Neovim AI layer; agentic mode and ACP/CLI-agent direction; useful if you want IDE-like AI interactions inside Neovim. | | MCPHub.nvim | MCP client/manager inside Neovim; integrates MCP tools/resources/prompts with CodeCompanion/Avante/CopilotChat and includes LSP diagnostics support. | | claudecode.nvim | Claude Code IDE bridge: WebSocket server, split terminal, send visual selection/files, editor diffs, diagnostics/workspace info. | | Commandr | L3 bus: task lifecycle, approvals, neutral progress, events. | | DiffViewer | L5 review/evidence UI; should interoperate with Neovim rather than replace it. | *** ## LSP/DAP Policy With Mason If Mason is already the operator's LSP/DAP manager, do not duplicate that by enabling every Claude Code LSP plugin globally. Use two separate lanes: | Lane | Owner | Startup | | -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | | Human IDE lane | Neovim + Mason + lspconfig + nvim-dap | Starts when human opens project/buffers; servers attach by filetype/root. | | Agent execution lane | omp, Claude Code plugin LSPs, OpenCode LSP events, or runner tools | Lazy per runner/worktree only when agent needs code intelligence. | Mason is the right source for the human lane because it already manages LSP servers, DAP servers, linters, and formatters. Agent setup should know that Neovim/Mason may already provide the operator's diagnostics and debug surface, but should not assume agents can directly read Neovim state unless a bridge is configured. *** ## Startup Recommendation Do not spin up LSPs at generic AI session start. Use this policy: 1. **Neovim opened for project**: Mason/lspconfig starts relevant LSPs naturally by buffer/root. DAP adapters are available on demand. 2. **Agent starts code task**: runner detects project stack and either uses its own LSP capability (`omp`, OpenCode events, Claude LSP plugin) or relies on typecheck/tests if no LSP bridge exists. 3. **Human review begins**: Neovim auto-reloads agent edits, diffview refreshes, LSP diagnostics update, DAP can reproduce/debug issues. 4. **Evidence handoff**: summaries from LSP/DAP/diffview can be turned into Commandr neutral progress or DiffViewer review artifacts. This avoids idle global daemons while preserving IDE-quality feedback when actual code is open. *** ## Neovim UX Needed for Agent Work The Xata workflow captures the practical minimum: * auto-reload buffers when agents write files outside Neovim * skip modified buffers so human edits are not clobbered * refresh diffview when `.git/` or non-ignored files change * yank selected code with relative/absolute file path and line range for agent prompts * keep the approach agent-agnostic: Claude Code, Aider, OpenCode, Gemini, Codex, etc. Add our control-plane-specific needs: * show current Commandr task id/status in statusline * quick open claimed packet / approval token / events log * send current selection as `task_annotation` or agent steer * pin current diff hunk/log line as evidence * open DiffViewer review package from Neovim * expose LSP diagnostics summary to review package generator * expose DAP session result as evidence when debugging a failing test or runtime bug *** ## AI Plugins: Where They Fit There are two valid modes: | Mode | Good for | Tools | | --------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Agent outside editor, Neovim as cockpit | Most Commandr/DiffViewer workflow; keeps agents swappable and bus-centered | Claude Code/OpenCode/Codex in tmux/terminal, claudecode.nvim bridge, DiffViewer, diffview\.nvim | | Agent inside editor | Short local refactors, prompt from selection, LSP-aware chat, MCP experiments | CodeCompanion.nvim, Avante.nvim, MCPHub.nvim | Do not make an editor plugin the authoritative task queue. Let editor AI plugins consume context and propose edits, but Commandr remains lifecycle source of truth when a task is in the bus. *** ## DAP as Agent Evidence DAP matters because many agent failures are runtime failures that LSP/typecheck cannot catch. Neovim already has the right mental model: breakpoints, launch/attach, step, inspect variables, stack frames. For our system: * DAP session setup remains Neovim/operator-owned through `nvim-dap` and Mason-installed adapters. * Agents can request a debug reproduction, but human/operator decides whether to run debugger unless we later add a safe runner action. * Debug results should become evidence artifacts: failing breakpoint, stack trace, variable values, reproduction steps. * DiffViewer/Tauri can render the artifact; Commandr records only neutral progress or artifact reference. *** ## Design Implications ### For `claude-setup/` Project onboarding should ask whether Neovim+Mason is the operator IDE. If yes: * record `operator_ide: neovim` * record `lsp_manager: mason` * record `dap_manager: mason+nvim-dap` * avoid globally enabling duplicate Claude LSP plugins by default * suggest Neovim reload/diffview/yank-context helpers ### For Commandr Commandr should know that LSP/DAP evidence may exist, but should not own it. It can accept neutral progress and future artifact references. ### For DiffViewer/Tauri DiffViewer should not try to replace Neovim. It should interoperate: * deep link to files/line ranges for Neovim * import LSP diagnostics summaries * import DAP/debug reproduction artifacts * show review packages and approvals in a richer UI ### For runner choice Use `omp` or another LSP-aware runner for autonomous code-changing tasks. Use Neovim/Mason for human inspection and small edits. Avoid forcing agents to drive Neovim directly unless using a deliberate bridge like `claudecode.nvim` or an MCP Neovim server. *** ## Open Questions * Should DiffViewer expose a `nvim://` or terminal command deep-link for file/line navigation? * Should Commandr define an artifact type for `lsp-diagnostics-summary` and `dap-debug-session`? * Should `claude-setup` install Neovim helper snippets, or only document expected capabilities? * Should MCPHub.nvim become the preferred path for Neovim-local MCP tools, or remain an experiment?