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?