opencode-nvim-diff-review 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Richards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# nvim-diff-review-opencode-plugin
+
+An agent-driven guided code review tool for Neovim and [OpenCode](https://opencode.ai). An AI agent walks you through code changes file by file, showing side-by-side diffs in Neovim while discussing the changes in a separate OpenCode chat.
+
+## How it works
+
+The plugin connects an OpenCode agent to Neovim's [diffview.nvim](https://github.com/sindrets/diffview.nvim) via Neovim's built-in RPC socket. The agent can open diffs, navigate between files, and query the current review state — all while the user interacts via the OpenCode chat.
+
+```
+┌────────────────────────────┬──────────────────────┐
+│                            │                      │
+│  Neovim showing diff of    │  OpenCode agent:     │
+│  src/store/selectors.js    │                      │
+│                            │  "I refactored the   │
+│  - old code in red         │   getBlockName func  │
+│  + new code in green       │   to handle the new  │
+│                            │   edge case where..." │
+│                            │                      │
+│                            │  Any questions about  │
+│                            │  these changes?       │
+└────────────────────────────┴──────────────────────┘
+```
+
+The review workflow:
+
+1. Agent opens a diff view in Neovim (scoped to specific files or all uncommitted changes)
+2. Agent explains the changes in the current file
+3. User asks questions or leaves feedback — agent notes it but **does not edit files**
+4. Agent navigates to the next file and repeats
+5. After the last file, agent closes the diff view
+6. Agent proposes a commit message and commits the original work
+7. If feedback was left, agent applies it as a separate commit
+8. Optionally, a second review of just the feedback changes
+
+## Components
+
+The plugin has two parts that are installed separately:
+
+### 1. Neovim plugin (`lua/diff-review/`)
+
+A Lua module that:
+
+- Registers a global `DiffviewState()` function queryable via Neovim's RPC socket
+- Provides diffview.nvim hooks that clean up buffers when the diff view is closed (so reviewed files don't linger as open tabs)
+
+### 2. OpenCode plugin (`opencode-plugin/index.ts`)
+
+An OpenCode plugin that registers a `diff_review` tool the AI agent uses to control the diff view. Actions:
+
+| Action | Description |
+|--------|-------------|
+| `open` | Open a diff view, optionally scoped to specific files or a git ref. Returns the file list and current position. |
+| `next` | Navigate to the next file. Detects and prevents wrap-around at the last file. |
+| `prev` | Navigate to the previous file. Detects and prevents wrap-around at the first file. |
+| `status` | Get current file and position without navigating. Includes the full file list. |
+| `close` | Close the diff view and clean up buffers. |
+
+## Dependencies
+
+- [Neovim](https://neovim.io/) 0.9+
+- [diffview.nvim](https://github.com/sindrets/diffview.nvim)
+- [OpenCode](https://opencode.ai) 1.3+
+
+## Installation
+
+### 1. Neovim plugin
+
+Using [lazy.nvim](https://github.com/folke/lazy.nvim):
+
+```lua
+{
+  "talldan/nvim-diff-review-opencode-plugin",
+  dependencies = { "sindrets/diffview.nvim" },
+  config = function()
+    require("diff-review").setup()
+  end,
+}
+```
+
+This also installs diffview.nvim as a dependency if you don't already have it. You can configure diffview.nvim separately — the plugin merges its hooks with any existing diffview hooks you have.
+
+### 2. OpenCode plugin
+
+Add the plugin to your `opencode.json` configuration:
+
+```json
+{
+  "plugin": ["github:talldan/nvim-diff-review-opencode-plugin"]
+}
+```
+
+This can go in your global config (`~/.config/opencode/opencode.json`) or a project-level config (`opencode.json` in your project root).
+
+Restart OpenCode to load the plugin. The `diff_review` tool will be available to the AI agent automatically.
+
+### 3. Neovim RPC socket
+
+The tool communicates with Neovim via its RPC socket. You need to:
+
+1. Start Neovim with a listen address:
+   ```bash
+   export NVIM_SOCKET=/tmp/nvim.sock
+   nvim --listen $NVIM_SOCKET
+   ```
+
+2. Make sure `NVIM_SOCKET` is set in the environment where OpenCode runs.
+
+If you use [CMUX](https://cmux.com), you can set this in your workspace configuration so both Neovim and OpenCode share the socket path automatically.
+
+## Design
+
+### Architecture
+
+```
+OpenCode (agent)                    Neovim (editor)
+     │                                   │
+     │  nvim --headless --server         │
+     │    $NVIM_SOCKET --remote-expr     │
+     │    "luaeval('...')"               │
+     │ ─────────────────────────────────>│
+     │                                   │
+     │  JSON response                    │
+     │ <─────────────────────────────────│
+     │                                   │
+```
+
+The tool uses Neovim's `--remote-expr` to evaluate Lua expressions on the running Neovim instance. This is a standard Neovim feature that works in any terminal — no CMUX or specific terminal emulator required.
+
+Key design decisions:
+
+- **`--headless` flag on remote calls**: Prevents Neovim from emitting terminal escape sequences when invoked from a subprocess (e.g., Bun's shell). Without this, the JSON response gets polluted with control codes.
+- **State queries via `DiffviewState()`**: A global Lua function registered at plugin load time. Returns JSON with the current file, position, and full file list. Registered as a global (not module-scoped) so it can be called via `luaeval()` without needing the module require path.
+- **Wrap-around prevention**: diffview.nvim wraps from the last file to the first (and vice versa) when navigating. The tool detects this by comparing indices before and after navigation, and undoes the wrap if detected.
+- **Buffer cleanup on close**: diffview.nvim intentionally keeps local file buffers open after closing (so you can continue editing). The plugin tracks which buffers existed before the review and removes any new ones on close — unless they have unsaved edits.
+- **Small delays after navigation**: 200-500ms sleeps after diffview commands to let the UI update before querying state. Without this, the state query can return stale data.
+
+### Review workflow instructions
+
+The tool description embeds detailed workflow instructions for the AI agent:
+
+- **Lint before review**: The agent is told to fix lint/format issues before opening the diff, so the user only sees clean changes.
+- **No edits during review**: The agent is explicitly instructed to never edit files during the review. Feedback is collected and applied afterward.
+- **Two-commit pattern**: Original work is committed first, then feedback changes are committed separately. This gives clean git history and allows the second review to show only the feedback diff.
+- **Interactive pacing**: The agent explains each file's changes, asks for feedback, and waits for the user's response before moving on.
+
+## Future improvements
+
+These were discussed during development but not yet implemented:
+
+### Chunk-level navigation
+
+Navigate within a file between individual hunks (like `git add -p`), not just between files. This would allow the agent to walk through a large file's changes piece by piece rather than presenting the whole diff at once.
+
+### Logical ordering
+
+Instead of reviewing files in filesystem order, the agent would use its understanding of the codebase to present changes in a narrative order — e.g., "first the data model change, then the API that uses it, then the UI that calls the API." This would make reviews of larger changesets more coherent.
+
+### Accept/reject per-hunk
+
+Allow the user to accept or reject individual hunks from the diff view, similar to `git add -p`. This would integrate with diffview.nvim's staging capabilities.
+
+### Line range focus
+
+The agent could jump to specific line ranges within a diff to highlight the key change, rather than showing the full file diff. Useful for large files where only a small section was modified.
+
+### OpenCode session diff integration
+
+Instead of using `git diff` to determine changed files, use OpenCode's `/session/:id/diff` API endpoint to get exactly which files the agent modified in the current session. This would avoid showing unrelated uncommitted changes.

package/lua/diff-review/init.lua

@@ -0,0 +1,154 @@
+-- diff-review: Neovim plugin for OpenCode-driven guided code reviews
+--
+-- Provides:
+-- 1. A global DiffviewState() function that external tools can query via Neovim's
+--    RPC socket to get the current diffview state (file, position, file list).
+-- 2. Diffview hooks that clean up buffers when the diff view is closed.
+--
+-- Requires: sindrets/diffview.nvim
+--
+-- Usage from outside Neovim:
+--   nvim --headless --server $NVIM_SOCKET --remote-expr "luaeval('DiffviewState()')"
+
+local M = {}
+
+--- Track which buffers existed before diffview opened.
+--- Used by the cleanup hooks to avoid removing buffers the user had open.
+local pre_diffview_bufs = {}
+
+--- Query the current diffview state.
+--- Returns a JSON string with:
+---   open: boolean          - whether diffview is active
+---   current_file: string?  - repo-relative path of the file being shown
+---   absolute_path: string? - absolute path on disk
+---   status: string?        - git status letter (M, A, D, R, etc.)
+---   index: number?         - 1-based position in the file list
+---   total: number?         - total number of changed files
+---   files: table?          - array of {path, status} for all files in the diff
+---
+--- Registered as a global function so it can be called via luaeval() from
+--- Neovim's --remote-expr without requiring the module path.
+function DiffviewState()
+  local ok, lib = pcall(require, "diffview.lib")
+  if not ok then
+    return vim.json.encode({ open = false, error = "diffview.nvim not loaded" })
+  end
+
+  local utils = require("diffview.utils")
+  local view = lib.get_current_view()
+  if not view then
+    return vim.json.encode({ open = false })
+  end
+
+  local panel = view.panel
+  local cur_file = panel.cur_file
+  local files = panel:ordered_file_list()
+  local total = #files
+
+  if not cur_file then
+    return vim.json.encode({ open = true, current_file = vim.NIL, index = 0, total = total })
+  end
+
+  local index = utils.vec_indexof(files, cur_file)
+
+  -- Build the list of all file paths for the summary
+  local all_files = {}
+  for _, f in ipairs(files) do
+    table.insert(all_files, { path = f.path, status = f.status })
+  end
+
+  return vim.json.encode({
+    open = true,
+    current_file = cur_file.path,
+    absolute_path = cur_file.absolute_path,
+    status = cur_file.status,
+    index = index,
+    total = total,
+    files = all_files,
+  })
+end
+
+--- Diffview hook: called when a diff view is opened.
+--- Snapshots the current buffer list so we know which buffers to clean up later.
+function M.on_view_opened(view)
+  pre_diffview_bufs = {}
+  for _, buf in ipairs(vim.api.nvim_list_bufs()) do
+    if vim.api.nvim_buf_is_loaded(buf) then
+      pre_diffview_bufs[buf] = true
+    end
+  end
+end
+
+--- Diffview hook: called when a diff view is closed.
+--- Cleans up buffers that diffview created but the user didn't have open before.
+--- - diffview:// internal buffers are always removed
+--- - Real file buffers opened by diffview are removed if they have no unsaved edits
+function M.on_view_closed(view)
+  vim.schedule(function()
+    for _, buf in ipairs(vim.api.nvim_list_bufs()) do
+      if vim.api.nvim_buf_is_valid(buf) and not pre_diffview_bufs[buf] then
+        local name = vim.api.nvim_buf_get_name(buf)
+        -- Always clean up diffview's internal buffers (diffview:// scheme)
+        if name:match("^diffview://") then
+          pcall(vim.api.nvim_buf_delete, buf, { force = true })
+        -- Also clean up real file buffers that diffview opened, but only if
+        -- they're unmodified (don't wipe user edits)
+        elseif vim.api.nvim_buf_is_loaded(buf) and not vim.bo[buf].modified then
+          pcall(vim.api.nvim_buf_delete, buf, {})
+        end
+      end
+    end
+    pre_diffview_bufs = {}
+  end)
+end
+
+--- Set up the plugin. Call this from your plugin spec or init.lua.
+--- Configures diffview.nvim hooks for buffer cleanup.
+---
+--- Example with lazy.nvim:
+---   {
+---     "your-username/nvim-diff-review-opencode-plugin",
+---     dependencies = { "sindrets/diffview.nvim" },
+---     config = function()
+---       require("diff-review").setup()
+---     end,
+---   }
+function M.setup(opts)
+  opts = opts or {}
+
+  -- Register the DiffviewState global function (already done at module load,
+  -- but this ensures it's available even if the module is lazy-loaded)
+  _G.DiffviewState = DiffviewState
+
+  -- Configure diffview hooks
+  local dv_ok, diffview = pcall(require, "diffview")
+  if not dv_ok then
+    vim.notify(
+      "[diff-review] diffview.nvim is required but not installed",
+      vim.log.levels.WARN
+    )
+    return
+  end
+
+  -- Get existing diffview config and merge our hooks
+  local config = require("diffview.config")
+  local existing_hooks = config.get_config().hooks or {}
+
+  local orig_view_opened = existing_hooks.view_opened
+  local orig_view_closed = existing_hooks.view_closed
+
+  diffview.setup({
+    hooks = vim.tbl_extend("force", existing_hooks, {
+      view_opened = function(view)
+        M.on_view_opened(view)
+        if orig_view_opened then orig_view_opened(view) end
+      end,
+      view_closed = function(view)
+        M.on_view_closed(view)
+        if orig_view_closed then orig_view_closed(view) end
+      end,
+    }),
+  })
+end
+
+return M

package/opencode-plugin/index.ts

@@ -0,0 +1,225 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+interface DiffviewFileInfo {
+  path: string
+  status: string
+}
+
+interface DiffviewState {
+  open: boolean
+  current_file?: string | null
+  absolute_path?: string
+  status?: string
+  index?: number
+  total?: number
+  files?: DiffviewFileInfo[]
+  error?: string
+}
+
+export const DiffReviewPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      diff_review: tool({
+        description:
+          "Control a diff review view in the user's Neovim editor. Use this to walk " +
+          "the user through code changes after completing a task.\n\n" +
+          "IMPORTANT: Before starting a review, ensure all changes are clean:\n" +
+          "- Run any relevant linters/formatters and fix issues BEFORE opening the diff\n" +
+          "- The user should only see final, clean changes — not intermediate lint fixes\n" +
+          "- If you discover lint errors during review, close the diff, fix them, then restart\n\n" +
+          "Workflow:\n" +
+          "1. Fix any lint/format issues in your changes first\n" +
+          "2. Call with action 'open' to show the diff (optionally scoped to specific files)\n" +
+          "   — the response includes a list of ALL files that will be reviewed\n" +
+          "3. Explain the changes visible in the current file (the response tells you which file is shown)\n" +
+          "4. Ask the user if they have questions or feedback about these changes\n" +
+          "5. If the user requests changes or leaves feedback on the current file, acknowledge it\n" +
+          "   and note it down — but DO NOT make any changes yet. Continue the review.\n" +
+          "6. Call with action 'next' to move to the next changed file\n" +
+          "   — when you reach the last file, 'next' will tell you there are no more files\n" +
+          "7. Repeat steps 3-6 for each file\n" +
+          "8. Call with action 'close' when the review is complete\n" +
+          "9. Propose a git commit message for the CURRENT changes and commit if the user approves\n" +
+          "10. If the user left feedback or change requests during the review, NOW apply them\n" +
+          "    — this creates a clean separation: one commit for the original work,\n" +
+          "    a second commit for review feedback changes\n" +
+          "11. If you made feedback changes, offer to walk through them with a second diff_review\n" +
+          "    — since the original work is already committed, this diff will only show\n" +
+          "    the feedback changes, making them easy to verify\n\n" +
+          "CRITICAL: During the review (steps 3-7), NEVER make changes to files.\n" +
+          "Only collect feedback. Apply changes AFTER the review is closed and the\n" +
+          "original work is committed.\n\n" +
+          "Every response includes the current file path and position (e.g., '2 of 3') " +
+          "so you always know where you are in the review. Use the 'status' action " +
+          "to re-orient if you lose track.",
+        args: {
+          action: tool.schema
+            .enum(["open", "next", "prev", "close", "status"])
+            .describe(
+              "open: show diff view in Neovim. " +
+              "next: navigate to next changed file. " +
+              "prev: navigate to previous changed file. " +
+              "close: close the diff view. " +
+              "status: get current file and position without navigating."
+            ),
+          files: tool.schema
+            .array(tool.schema.string())
+            .optional()
+            .describe(
+              "File paths to include in the diff (open only). " +
+              "Omit to show all uncommitted changes."
+            ),
+          ref: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Git ref to diff against (open only). " +
+              "Defaults to showing uncommitted changes vs HEAD. " +
+              "Examples: HEAD~3, a commit hash, origin/main"
+            ),
+        },
+        async execute(args, context) {
+          const socket = process.env.NVIM_SOCKET
+          if (!socket) {
+            return "NVIM_SOCKET environment variable is not set. " +
+              "Make sure Neovim is running with --listen and NVIM_SOCKET is exported.\n\n" +
+              "Quick setup:\n" +
+              "  export NVIM_SOCKET=/tmp/nvim.sock\n" +
+              "  nvim --listen $NVIM_SOCKET\n\n" +
+              "If using CMUX, the workspace command sets this automatically."
+          }
+
+          const nvimExpr = (expr: string) =>
+            Bun.$`nvim --headless --server ${socket} --remote-expr ${expr}`.text()
+
+          const getState = async (): Promise<DiffviewState> => {
+            try {
+              const raw = await nvimExpr(`luaeval("DiffviewState()")`)
+              return JSON.parse(raw.trim())
+            } catch {
+              return { open: false, error: "Could not query diffview state" }
+            }
+          }
+
+          const statusLabel = (status: string | undefined): string =>
+            status === "M" ? "modified" :
+            status === "A" ? "added" :
+            status === "D" ? "deleted" :
+            status === "R" ? "renamed" :
+            status ?? "changed"
+
+          const formatState = (state: DiffviewState): string => {
+            if (!state.open) return "Diff view is not open."
+            if (!state.current_file)
+              return `Diff view is open but no files to show (${state.total ?? 0} files total).`
+            return `Currently showing: ${state.current_file} (${statusLabel(state.status)}) — file ${state.index} of ${state.total}.`
+          }
+
+          const formatFileList = (state: DiffviewState): string => {
+            if (!state.files || state.files.length === 0) return ""
+            const list = state.files
+              .map((f, i) => `  ${i + 1}. ${f.path} (${statusLabel(f.status)})`)
+              .join("\n")
+            return `\nFiles to review:\n${list}`
+          }
+
+          try {
+            switch (args.action) {
+              case "open": {
+                let cmd = "DiffviewOpen"
+                if (args.ref) {
+                  cmd += ` ${args.ref}`
+                }
+                if (args.files && args.files.length > 0) {
+                  const escaped = args.files.map(f => f.replace(/ /g, "\\ ")).join(" ")
+                  cmd += ` -- ${escaped}`
+                }
+                await nvimExpr(`luaeval("vim.cmd('${cmd.replace(/'/g, "''")}')")`)
+                // Give diffview a moment to populate the file list
+                await Bun.sleep(500)
+                const state = await getState()
+                return `Opened diff view in Neovim` +
+                  (args.ref ? ` (comparing against ${args.ref})` : " (uncommitted changes vs HEAD)") +
+                  `. ${formatState(state)}` +
+                  formatFileList(state)
+              }
+
+              case "next": {
+                const before = await getState()
+                if (!before.open) return "Diff view is not open. Call with action 'open' first."
+
+                // If already on the last file, don't navigate (diffview wraps around)
+                if (before.index !== undefined && before.total !== undefined &&
+                    before.index >= before.total) {
+                  return `Already at the last file (file ${before.index} of ${before.total}). ` +
+                    `${formatState(before)} There are no more files to review. ` +
+                    "Use action 'close' to end the review."
+                }
+
+                await nvimExpr(`luaeval("require('diffview').emit('select_next_entry')")`)
+                await Bun.sleep(200)
+                const after = await getState()
+
+                // Detect wrap-around: if index went down, diffview wrapped to the beginning
+                if (before.index !== undefined && after.index !== undefined &&
+                    after.index < before.index) {
+                  // Undo the wrap by going back
+                  await nvimExpr(`luaeval("require('diffview').emit('select_prev_entry')")`)
+                  await Bun.sleep(200)
+                  const restored = await getState()
+                  return `Already at the last file (file ${restored.index} of ${restored.total}). ` +
+                    `${formatState(restored)} There are no more files to review. ` +
+                    "Use action 'close' to end the review."
+                }
+
+                return `Navigated to next file. ${formatState(after)}`
+              }
+
+              case "prev": {
+                const before = await getState()
+                if (!before.open) return "Diff view is not open. Call with action 'open' first."
+
+                // If already on the first file, don't navigate (diffview wraps around)
+                if (before.index !== undefined && before.index <= 1) {
+                  return `Already at the first file (file ${before.index} of ${before.total}). ` +
+                    `${formatState(before)} There are no previous files.`
+                }
+
+                await nvimExpr(`luaeval("require('diffview').emit('select_prev_entry')")`)
+                await Bun.sleep(200)
+                const after = await getState()
+
+                // Detect wrap-around: if index went up, diffview wrapped to the end
+                if (before.index !== undefined && after.index !== undefined &&
+                    after.index > before.index) {
+                  // Undo the wrap by going forward
+                  await nvimExpr(`luaeval("require('diffview').emit('select_next_entry')")`)
+                  await Bun.sleep(200)
+                  const restored = await getState()
+                  return `Already at the first file (file ${restored.index} of ${restored.total}). ` +
+                    `${formatState(restored)} There are no previous files.`
+                }
+
+                return `Navigated to previous file. ${formatState(after)}`
+              }
+
+              case "status": {
+                const state = await getState()
+                if (!state.open) return "Diff view is not currently open."
+                return `${formatState(state)}${formatFileList(state)}`
+              }
+
+              case "close": {
+                await nvimExpr(`luaeval("require('diffview').close()")`)
+                return "Closed the diff view in Neovim."
+              }
+            }
+          } catch (e: any) {
+            return `Failed to control Neovim diff view: ${e.message ?? e}. ` +
+              `Is Neovim running with --listen ${socket} and the diff-review plugin installed?`
+          }
+        },
+      }),
+    },
+  }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "opencode-nvim-diff-review",
+  "version": "0.1.0",
+  "description": "Agent-driven guided code review for Neovim + OpenCode",
+  "main": "opencode-plugin/index.ts",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "neovim",
+    "nvim",
+    "diff",
+    "diffview",
+    "code-review"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/talldan/nvim-diff-review-opencode-plugin.git"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  }
+}