opencode-nvim-diff-review 0.1.0 → 0.3.0

package/README.md

@@ -1,36 +1,38 @@
 # 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.
+An agent-driven guided code review tool for Neovim and [OpenCode](https://opencode.ai). An AI agent walks you through code changes hunk by hunk, 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.
+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 query all change hunks, reorder them for narrative coherence, open diffs, and navigate between hunks — 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..." │
+│  (cursor at hunk 2 of 3)   │  "I added validation  │
+│                            │   for the edge case   │
+│  - old code in red         │   where the block     │
+│  + new code in green       │   name is             │
+│                            │   undefined..."       │
 │                            │                      │
 │                            │  Any questions about  │
-│                            │  these changes?       │
+│                            │  this change?         │
 └────────────────────────────┴──────────────────────┘
 ```
 
 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
+1. Agent queries all change hunks across all files
+2. Agent decides a review order — reordering for narrative coherence (e.g., data model first, then API, then UI) or using natural order for small changes
+3. Agent opens the diff view and begins the review walk-through
+4. For each hunk: agent explains the change, user asks questions or leaves feedback
+5. Agent notes feedback but **does not edit files** during the review
+6. After the last hunk, agent closes the diff view
+7. Agent proposes a commit message and commits the original work
+8. If feedback was left, agent applies it as a separate commit
+9. Optionally, a second review of just the feedback changes
 
 ## Components
 
@@ -40,7 +42,10 @@ The plugin has two parts that are installed separately:
 
 A Lua module that:
 
-- Registers a global `DiffviewState()` function queryable via Neovim's RPC socket
+- Registers global functions queryable via Neovim's RPC socket:
+  - `DiffviewState()` — current diffview state (file, position, file list)
+  - `DiffviewHunks(ref?)` — all diff hunks as a flat array, parsed from `git diff` output using diffview.nvim's diff parser
+  - `DiffviewGoTo(file, line)` — navigate diffview to a specific file and line
 - 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`)
@@ -49,11 +54,12 @@ An OpenCode plugin that registers a `diff_review` tool the AI agent uses to cont
 
 | 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. |
+| `get_hunks` | Get all diff hunks across all files as a flat array. Each hunk is self-contained with file path, status, and line ranges. Optionally scoped to specific files or a git ref. |
+| `start_review` | Open the diff view and begin the review walk-through. Accepts an optional ordered array of hunks (from `get_hunks`) to control review order. If omitted, uses natural hunk order. Navigates to the first item. |
+| `next` | Navigate to the next item in the review queue. Prevents wrap-around at the last item. |
+| `prev` | Navigate to the previous item in the review queue. Prevents wrap-around at the first item. |
+| `status` | Get current position in the review queue without navigating. |
+| `close` | Close the diff view and clear the review queue. |
 
 ## Dependencies
 
@@ -85,7 +91,7 @@ Add the plugin to your `opencode.json` configuration:
 
 ```json
 {
-  "plugin": ["github:talldan/nvim-diff-review-opencode-plugin"]
+  "plugin": ["opencode-nvim-diff-review"]
 }
 ```
 
@@ -95,15 +101,29 @@ Restart OpenCode to load the plugin. The `diff_review` tool will be available to
 
 ### 3. Neovim RPC socket
 
-The tool communicates with Neovim via its RPC socket. You need to:
+The tool communicates with Neovim via its RPC socket. In most cases, **no configuration is needed** — the tool auto-discovers running Neovim instances.
 
-1. Start Neovim with a listen address:
-   ```bash
-   export NVIM_SOCKET=/tmp/nvim.sock
-   nvim --listen $NVIM_SOCKET
-   ```
+#### Auto-discovery (default)
 
-2. Make sure `NVIM_SOCKET` is set in the environment where OpenCode runs.
+The tool automatically finds Neovim by:
+
+1. Checking the `NVIM_SOCKET` environment variable (if set, always used)
+2. Scanning for Neovim sockets in standard locations (`$TMPDIR` and `/tmp`)
+3. Preferring the Neovim instance whose working directory matches the current project
+4. Falling back to the first live Neovim instance found
+
+This means if you just run `nvim` in your project directory, OpenCode will find it automatically.
+
+#### Explicit configuration (optional)
+
+If auto-discovery doesn't work for your setup (e.g., multiple Neovim instances in the same directory), you can set the socket path explicitly:
+
+```bash
+export NVIM_SOCKET=/tmp/nvim.sock
+nvim --listen $NVIM_SOCKET
+```
+
+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.
 
@@ -126,42 +146,60 @@ OpenCode (agent)                    Neovim (editor)
 
 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:
+### Hunk-based review
+
+The review operates at the **hunk level** rather than the file level. This means:
+
+- A file with 3 separate change regions is presented as 3 review items
+- The agent can reorder hunks across files for narrative coherence (e.g., show a data model change in `model.ts` before the API endpoint in `api.ts` that uses it, even if they're in different files)
+- Small files with a single change are naturally one review item
+- The agent can filter out trivial hunks (e.g., import reordering) from the review
+
+Hunks are retrieved by running `git diff -U0` and parsing the output with diffview.nvim's built-in unified diff parser (`diffview.vcs.utils.parse_diff`). The `-U0` flag produces zero-context hunks, giving exact change boundaries.
+
+### Review queue
+
+The review queue is managed on the TypeScript (OpenCode plugin) side. It holds:
+
+- An ordered array of hunk items (set by `start_review`)
+- The current position in the queue (advanced by `next`/`prev`)
+
+The Lua (Neovim) side is stateless — it provides functions to query hunks and navigate the diff view, but doesn't track review progress. This keeps the Neovim plugin simple and the state management in one place.
+
+### 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.
+- **State queries via global Lua functions**: `DiffviewState()`, `DiffviewHunks()`, and `DiffviewGoTo()` are registered as globals so they can be called via `luaeval()` from Neovim's `--remote-expr` without needing the module require path.
+- **Wrap-around prevention**: The tool checks queue bounds before navigating and refuses to advance past the first/last item.
 - **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.
+- **Small delays after navigation**: 300ms sleeps after diffview commands to let the UI update before querying state. Without this, the state query can return stale data.
+- **Socket auto-discovery**: When `NVIM_SOCKET` is not set, the tool scans `$TMPDIR/nvim.$USER/` and `/tmp` for Neovim socket files, verifies each is live, and uses `lsof` to match the Neovim process's working directory against the current project. This allows zero-configuration usage in ad-hoc terminals — just run `nvim` and OpenCode will find it.
 
 ### 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.
+- **Narrative ordering**: The agent analyzes hunks and reorders them for coherent presentation — explaining foundational changes before dependent ones.
 - **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.
+- **Interactive pacing**: The agent explains each hunk, 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
+### Expand (surrounding context)
 
-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.
+Show surrounding code context around the current hunk. Useful when the agent or user needs to see more of the file to understand a change. Would be implemented as an `expand` action.
 
 ### 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
+### Logical ordering
 
-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.
+Instead of the agent deciding order ad-hoc, build smarter ordering heuristics — e.g., analyzing import graphs to automatically determine dependency order between changed files.
 
 ### OpenCode session diff integration
 

package/lua/diff-review/init.lua

@@ -3,12 +3,19 @@
 -- 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.
+-- 2. A global DiffviewHunks() function that returns all diff hunks across all files
+--    as a flat array, using diffview.nvim's diff parser on git diff output.
+-- 3. A global DiffviewGoTo(file, line) function that navigates diffview to a
+--    specific file and line number.
+-- 4. 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()')"
+--   nvim --headless --server $NVIM_SOCKET --remote-expr "luaeval('DiffviewHunks()')"
+--   nvim --headless --server $NVIM_SOCKET --remote-expr "luaeval('DiffviewHunks(\"HEAD~3\")')"
+--   nvim --headless --server $NVIM_SOCKET --remote-expr "luaeval('DiffviewGoTo(\"src/foo.ts\", 42)')"
 
 local M = {}
 
@@ -68,6 +75,165 @@ function DiffviewState()
   })
 end
 
+--- Get all diff hunks across all files as a flat array.
+---
+--- Runs `git diff` and parses the output using diffview.nvim's diff parser.
+--- Each hunk is a self-contained object with its file path, git status, and
+--- line range information.
+---
+--- @param ref string? Optional git ref to diff against (e.g. "HEAD~3").
+---                    Defaults to diffing uncommitted changes vs HEAD.
+---                    If diffview is open and has a rev_arg, that is used as
+---                    the default instead.
+--- @return string JSON-encoded flat array of hunk objects:
+---   [{ file, status, old_start, old_count, new_start, new_count, header }]
+function DiffviewHunks(ref)
+  local ok, lib = pcall(require, "diffview.lib")
+  if not ok then
+    return vim.json.encode({ error = "diffview.nvim not loaded" })
+  end
+
+  local vcs_utils = require("diffview.vcs.utils")
+
+  -- Determine the git toplevel directory
+  local toplevel = vim.fn.systemlist("git rev-parse --show-toplevel")[1]
+  if vim.v.shell_error ~= 0 or not toplevel then
+    return vim.json.encode({ error = "Not in a git repository" })
+  end
+
+  -- If diffview is open, try to use its rev_arg as the default ref
+  if not ref then
+    local view = lib.get_current_view()
+    if view and view.rev_arg and view.rev_arg ~= "" then
+      ref = view.rev_arg
+    end
+  end
+
+  -- Get git status for each file (to include status letters in hunk data)
+  -- Use --name-status with the diff to get file statuses
+  local status_cmd = "git diff --name-status"
+  if ref then
+    status_cmd = status_cmd .. " " .. ref
+  end
+  local status_lines = vim.fn.systemlist(status_cmd)
+  local file_statuses = {}
+  for _, line in ipairs(status_lines) do
+    local status, path = line:match("^(%a)%s+(.+)$")
+    if status and path then
+      file_statuses[path] = status
+    end
+  end
+
+  -- Run git diff to get the full patch output
+  local diff_cmd = "git diff -U0"
+  if ref then
+    diff_cmd = diff_cmd .. " " .. ref
+  end
+  local diff_lines = vim.fn.systemlist(diff_cmd)
+  if vim.v.shell_error ~= 0 then
+    return vim.json.encode({ error = "git diff failed" })
+  end
+
+  if #diff_lines == 0 then
+    return vim.json.encode({})
+  end
+
+  -- Parse the diff using diffview's parser
+  local file_diffs = vcs_utils.parse_diff(diff_lines)
+
+  -- Flatten into a single array: one entry per hunk, each with its file info
+  local hunks = {}
+  for _, file_diff in ipairs(file_diffs) do
+    local path = file_diff.path_new or file_diff.path_old or ""
+    local status = file_statuses[path] or "M"
+
+    for _, hunk in ipairs(file_diff.hunks) do
+      local header = string.format(
+        "@@ -%d,%d +%d,%d @@",
+        hunk.old_row, hunk.old_size, hunk.new_row, hunk.new_size
+      )
+      table.insert(hunks, {
+        file = path,
+        status = status,
+        old_start = hunk.old_row,
+        old_count = hunk.old_size,
+        new_start = hunk.new_row,
+        new_count = hunk.new_size,
+        header = header,
+      })
+    end
+  end
+
+  return vim.json.encode(hunks)
+end
+
+--- Navigate diffview to a specific file and line number.
+---
+--- Finds the file in diffview's file list, switches to it if needed,
+--- then moves the cursor to the specified line in the right-hand (new) buffer.
+---
+--- @param file string Repo-relative file path
+--- @param line number Line number to jump to (in the new version of the file)
+--- @return string JSON-encoded result: { ok: true } or { error: string }
+function DiffviewGoTo(file, line)
+  local ok, lib = pcall(require, "diffview.lib")
+  if not ok then
+    return vim.json.encode({ error = "diffview.nvim not loaded" })
+  end
+
+  local view = lib.get_current_view()
+  if not view then
+    return vim.json.encode({ error = "diffview is not open" })
+  end
+
+  local utils = require("diffview.utils")
+  local panel = view.panel
+  local files = panel:ordered_file_list()
+
+  -- Find the target file in the file list
+  local target = nil
+  for _, f in ipairs(files) do
+    if f.path == file then
+      target = f
+      break
+    end
+  end
+
+  if not target then
+    return vim.json.encode({ error = "File not found in diffview: " .. file })
+  end
+
+  -- Switch to the target file if it's not already the current one
+  local cur_file = panel.cur_file
+  if not cur_file or cur_file.path ~= file then
+    view:set_file(target)
+  end
+
+  -- Move cursor to the target line in the right-hand (new version) buffer.
+  -- The layout has windows a (left/old) and b (right/new).
+  -- We need to wait briefly for the file switch to complete, then find
+  -- the right window and set the cursor.
+  vim.schedule(function()
+    -- Find the window showing the "b" (new) side of the diff
+    local layout = target.layout
+    if layout and layout.b and layout.b.file then
+      local b_win = layout.b.win
+      if b_win and vim.api.nvim_win_is_valid(b_win.id) then
+        -- Clamp line to buffer length
+        local bufnr = layout.b.file.bufnr
+        local max_line = vim.api.nvim_buf_line_count(bufnr)
+        local target_line = math.min(math.max(line or 1, 1), max_line)
+        vim.api.nvim_win_set_cursor(b_win.id, { target_line, 0 })
+        -- Center the view on the target line
+        vim.api.nvim_set_current_win(b_win.id)
+        vim.cmd("normal! zz")
+      end
+    end
+  end)
+
+  return vim.json.encode({ ok = true })
+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)
@@ -103,7 +269,8 @@ function M.on_view_closed(view)
 end
 
 --- Set up the plugin. Call this from your plugin spec or init.lua.
---- Configures diffview.nvim hooks for buffer cleanup.
+--- Configures diffview.nvim hooks for buffer cleanup and registers global
+--- functions for external tool access.
 ---
 --- Example with lazy.nvim:
 ---   {
@@ -116,9 +283,11 @@ 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)
+  -- Register global functions (already defined at module load,
+  -- but this ensures they're available even if the module is lazy-loaded)
   _G.DiffviewState = DiffviewState
+  _G.DiffviewHunks = DiffviewHunks
+  _G.DiffviewGoTo = DiffviewGoTo
 
   -- Configure diffview hooks
   local dv_ok, diffview = pcall(require, "diffview")

package/opencode-plugin/index.ts

@@ -1,8 +1,15 @@
 import { type Plugin, tool } from "@opencode-ai/plugin"
 
-interface DiffviewFileInfo {
-  path: string
+// --- Types ---
+
+interface HunkItem {
+  file: string
   status: string
+  old_start: number
+  old_count: number
+  new_start: number
+  new_count: number
+  header: string
 }
 
 interface DiffviewState {
@@ -12,10 +19,124 @@ interface DiffviewState {
   status?: string
   index?: number
   total?: number
-  files?: DiffviewFileInfo[]
+  files?: { path: string; status: string }[]
   error?: string
 }
 
+// --- Review queue state (persists across tool calls within a session) ---
+
+let reviewQueue: HunkItem[] = []
+let reviewPosition = -1 // -1 means review not started
+let reviewRef: string | undefined
+let reviewFiles: string[] | undefined
+
+// --- Neovim socket discovery ---
+
+/**
+ * Discover a Neovim RPC socket when NVIM_SOCKET is not explicitly set.
+ *
+ * Strategy:
+ * 1. Check NVIM_SOCKET env var (always wins)
+ * 2. Scan for socket files in known locations
+ * 3. Verify each is live by attempting a connection
+ * 4. Prefer the Neovim instance whose cwd matches ours (same project)
+ * 5. Fall back to the first live socket found
+ */
+const discoverNvimSocket = async (): Promise<string | null> => {
+  // 1. Explicit env var — skip discovery entirely
+  if (process.env.NVIM_SOCKET) return process.env.NVIM_SOCKET
+
+  // 2. Scan for socket files
+  const tmpdir = process.env.TMPDIR || "/tmp"
+  const user = process.env.USER || "unknown"
+  let socketPaths: string[] = []
+
+  try {
+    const output =
+      await Bun.$`find -L ${tmpdir}/nvim.${user} /tmp -maxdepth 4 -type s -name "nvim*" 2>/dev/null`.text()
+    socketPaths = output.trim().split("\n").filter(Boolean)
+  } catch {}
+
+  if (socketPaths.length === 0) return null
+
+  // 3 & 4. Check each socket — prefer cwd match, fall back to first live one
+  const ourCwd = process.cwd()
+  let fallback: string | null = null
+
+  for (const socketPath of socketPaths) {
+    try {
+      // Verify socket is live with a simple expression
+      await Bun.$`nvim --headless --server ${socketPath} --remote-expr "1+1"`.text()
+
+      // Try to get the PID from the socket filename (default sockets: nvim.<pid>.0)
+      let pid: string | undefined
+      const pidFromName = socketPath.match(/nvim\.(\d+)\.\d+$/)
+      if (pidFromName) {
+        pid = pidFromName[1]
+      } else {
+        // For --listen sockets (no PID in filename), find the owning process
+        try {
+          const lsof = await Bun.$`lsof ${socketPath} 2>/dev/null`.text()
+          const pidMatch = lsof.match(/nvim\s+(\d+)/)
+          if (pidMatch) pid = pidMatch[1]
+        } catch {}
+      }
+
+      // Get the cwd of the Neovim process and compare with ours
+      if (pid) {
+        try {
+          const lsof = await Bun.$`lsof -p ${pid} -Fn 2>/dev/null`.text()
+          const cwdMatch = lsof.match(/fcwd\nn(.+)/)
+          if (cwdMatch && cwdMatch[1] === ourCwd) {
+            return socketPath // Exact cwd match — this is our Neovim
+          }
+        } catch {}
+      }
+
+      // Remember the first live socket as fallback
+      if (!fallback) fallback = socketPath
+    } catch {
+      // Socket not responsive — stale socket from a crashed Neovim, skip it
+    }
+  }
+
+  return fallback
+}
+
+// --- Helpers ---
+
+const statusLabel = (status: string | undefined): string =>
+  status === "M" ? "modified" :
+  status === "A" ? "added" :
+  status === "D" ? "deleted" :
+  status === "R" ? "renamed" :
+  status ?? "changed"
+
+const formatHunkPosition = (): string => {
+  if (reviewQueue.length === 0) return "No review in progress."
+  const item = reviewQueue[reviewPosition]
+  return `Reviewing: ${item.file} (${statusLabel(item.status)}) ${item.header} — item ${reviewPosition + 1} of ${reviewQueue.length}.`
+}
+
+/**
+ * Match an order item from the agent to a hunk in the available hunks list.
+ * Identity is {file, old_start, new_start}.
+ */
+const findHunk = (
+  hunks: HunkItem[],
+  orderItem: { file: string; old_start: number; old_count: number; new_start: number; new_count: number }
+): HunkItem | undefined =>
+  hunks.find(
+    h =>
+      h.file === orderItem.file &&
+      h.old_start === orderItem.old_start &&
+      h.old_count === orderItem.old_count &&
+      h.new_start === orderItem.new_start &&
+      h.new_count === orderItem.new_count
+  )
+
+// --- Plugin ---
+
 export const DiffReviewPlugin: Plugin = async (ctx) => {
   return {
     tool: {
@@ -29,64 +150,90 @@ export const DiffReviewPlugin: Plugin = async (ctx) => {
           "- 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" +
+          "2. Call with action 'get_hunks' to retrieve all change hunks across all files.\n" +
+          "   Each hunk includes file path, status, and line range info.\n" +
+          "3. Analyze the hunks and decide a review order. Reorder them for narrative\n" +
+          "   coherence — e.g. show the data model change before the API that uses it,\n" +
+          "   then the UI that calls the API. For small changes, the natural order is fine.\n" +
+          "   You may also filter out hunks that are trivial (e.g. import reordering).\n" +
+          "4. Call with action 'start_review' with the ordered hunks array to open the diff\n" +
+          "   view and begin. If you omit the order, natural hunk order is used.\n" +
+          "5. Explain the current hunk shown in the diff view.\n" +
+          "6. Ask the user if they have questions or feedback about these changes.\n" +
+          "7. If the user requests changes or leaves feedback, acknowledge it and note it\n" +
+          "   down — but DO NOT make any changes yet. Continue the review.\n" +
+          "8. Call with action 'next' to advance to the next item in the review queue.\n" +
+          "   When you reach the last item, 'next' will tell you there are no more items.\n" +
+          "9. Repeat steps 5-8 for each item\n" +
+          "10. Call with action 'close' when the review is complete\n" +
+          "11. Propose a git commit message for the CURRENT changes and commit if the user approves\n" +
+          "12. 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" +
+          "13. 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" +
+          "CRITICAL: During the review (steps 5-9), 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') " +
+          "Every response includes the current item and position (e.g., 'item 2 of 5') " +
           "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"])
+            .enum(["get_hunks", "start_review", "next", "prev", "status", "close"])
             .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."
+              "get_hunks: retrieve all diff hunks across all files as a flat array. " +
+              "start_review: open the diff view and begin reviewing, optionally with a custom order. " +
+              "next: navigate to the next item in the review queue. " +
+              "prev: navigate to the previous item in the review queue. " +
+              "status: get current position in the review queue without navigating. " +
+              "close: close the diff view and end the review."
+            ),
+          ref: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Git ref to diff against (get_hunks and start_review only). " +
+              "Defaults to showing uncommitted changes vs HEAD. " +
+              "Examples: HEAD~3, a commit hash, origin/main"
             ),
           files: tool.schema
             .array(tool.schema.string())
             .optional()
             .describe(
-              "File paths to include in the diff (open only). " +
-              "Omit to show all uncommitted changes."
+              "File paths to include in the diff (get_hunks and start_review only). " +
+              "Omit to include all uncommitted changes."
             ),
-          ref: tool.schema
-            .string()
+          order: tool.schema
+            .array(
+              tool.schema.object({
+                file: tool.schema.string().describe("Repo-relative file path"),
+                old_start: tool.schema.number().describe("Start line in old version"),
+                old_count: tool.schema.number().describe("Line count in old version"),
+                new_start: tool.schema.number().describe("Start line in new version"),
+                new_count: tool.schema.number().describe("Line count in new version"),
+              })
+            )
             .optional()
             .describe(
-              "Git ref to diff against (open only). " +
-              "Defaults to showing uncommitted changes vs HEAD. " +
-              "Examples: HEAD~3, a commit hash, origin/main"
+              "Custom review order (start_review only). Array of hunk identifiers " +
+              "from the get_hunks response, in the order you want to review them. " +
+              "Each item needs: file, old_start, old_count, new_start, new_count. " +
+              "Omit to use the natural hunk order."
             ),
         },
         async execute(args, context) {
-          const socket = process.env.NVIM_SOCKET
+          const socket = await discoverNvimSocket()
           if (!socket) {
-            return "NVIM_SOCKET environment variable is not set. " +
-              "Make sure Neovim is running with --listen and NVIM_SOCKET is exported.\n\n" +
+            return "Could not find a running Neovim instance.\n\n" +
+              "The tool looks for Neovim in this order:\n" +
+              "1. NVIM_SOCKET environment variable (if set)\n" +
+              "2. Neovim instances whose working directory matches this project\n" +
+              "3. Any running Neovim instance\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."
+              "  nvim --listen $NVIM_SOCKET"
           }
 
           const nvimExpr = (expr: string) =>
@@ -101,117 +248,172 @@ export const DiffReviewPlugin: Plugin = async (ctx) => {
             }
           }
 
-          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 getHunks = async (ref?: string): Promise<HunkItem[]> => {
+            const luaArg = ref ? `"${ref.replace(/"/g, '\\"')}"` : ""
+            const raw = await nvimExpr(`luaeval("DiffviewHunks(${luaArg})")`)
+            const parsed = JSON.parse(raw.trim())
+            if (parsed.error) throw new Error(parsed.error)
+            return parsed as HunkItem[]
           }
 
-          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}`
+          const goToHunk = async (item: HunkItem): Promise<void> => {
+            const file = item.file.replace(/"/g, '\\"')
+            // Navigate to the new_start line (the line in the new version)
+            const line = item.new_start > 0 ? item.new_start : 1
+            const raw = await nvimExpr(
+              `luaeval("DiffviewGoTo('${file}', ${line})")`
+            )
+            const result = JSON.parse(raw.trim())
+            if (result.error) throw new Error(result.error)
+            // Give diffview time to switch files and position the cursor
+            await Bun.sleep(300)
           }
 
           try {
             switch (args.action) {
-              case "open": {
+              case "get_hunks": {
+                // Store ref/files for later use by start_review
+                reviewRef = args.ref
+                reviewFiles = args.files
+
+                const hunks = await getHunks(args.ref)
+
+                if (hunks.length === 0) {
+                  return "No changes found." +
+                    (args.ref ? ` (compared against ${args.ref})` : "")
+                }
+
+                // Summarize: count files and hunks
+                const fileSet = new Set(hunks.map(h => h.file))
+                const summary = `Found ${hunks.length} hunk${hunks.length === 1 ? "" : "s"} ` +
+                  `across ${fileSet.size} file${fileSet.size === 1 ? "" : "s"}` +
+                  (args.ref ? ` (compared against ${args.ref})` : "") + ".\n\n"
+
+                return summary + JSON.stringify(hunks, null, 2)
+              }
+
+              case "start_review": {
+                // Use ref/files from get_hunks if not explicitly provided
+                const ref = args.ref ?? reviewRef
+                const files = args.files ?? reviewFiles
+
+                // Open diffview
                 let cmd = "DiffviewOpen"
-                if (args.ref) {
-                  cmd += ` ${args.ref}`
+                if (ref) {
+                  cmd += ` ${ref}`
                 }
-                if (args.files && args.files.length > 0) {
-                  const escaped = args.files.map(f => f.replace(/ /g, "\\ ")).join(" ")
+                if (files && files.length > 0) {
+                  const escaped = 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
+                // Give diffview time 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)
+
+                // Build the review queue
+                if (args.order && args.order.length > 0) {
+                  // Agent provided a custom order — resolve each item to a full hunk
+                  const allHunks = await getHunks(ref)
+                  const queue: HunkItem[] = []
+                  const unmatched: string[] = []
+
+                  for (const orderItem of args.order) {
+                    const match = findHunk(allHunks, orderItem)
+                    if (match) {
+                      queue.push(match)
+                    } else {
+                      unmatched.push(`${orderItem.file} ${orderItem.old_start}→${orderItem.new_start}`)
+                    }
+                  }
+
+                  if (queue.length === 0) {
+                    return "Could not match any items in the provided order to actual hunks. " +
+                      `Unmatched: ${unmatched.join(", ")}. ` +
+                      "Call 'get_hunks' to see available hunks."
+                  }
+
+                  reviewQueue = queue
+
+                  if (unmatched.length > 0) {
+                    // Warn but proceed with what we have
+                  }
+                } else {
+                  // No custom order — use natural hunk order
+                  reviewQueue = await getHunks(ref)
+
+                  if (reviewQueue.length === 0) {
+                    return "Opened diff view but no hunks found." +
+                      (ref ? ` (compared against ${ref})` : "")
+                  }
+                }
+
+                // Navigate to the first item
+                reviewPosition = 0
+                await goToHunk(reviewQueue[0])
+
+                return `Started review with ${reviewQueue.length} item${reviewQueue.length === 1 ? "" : "s"}` +
+                  (ref ? ` (comparing against ${ref})` : " (uncommitted changes vs HEAD)") +
+                  `. ${formatHunkPosition()}`
               }
 
               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."
+                if (reviewQueue.length === 0) {
+                  return "No review in progress. Call 'start_review' first."
                 }
 
-                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. ` +
+                if (reviewPosition >= reviewQueue.length - 1) {
+                  return `Already at the last item (item ${reviewPosition + 1} of ${reviewQueue.length}). ` +
+                    `${formatHunkPosition()} There are no more items to review. ` +
                     "Use action 'close' to end the review."
                 }
 
-                return `Navigated to next file. ${formatState(after)}`
+                reviewPosition++
+                await goToHunk(reviewQueue[reviewPosition])
+
+                return `Navigated to next item. ${formatHunkPosition()}`
               }
 
               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.`
+                if (reviewQueue.length === 0) {
+                  return "No review in progress. Call 'start_review' first."
                 }
 
-                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.`
+                if (reviewPosition <= 0) {
+                  return `Already at the first item (item ${reviewPosition + 1} of ${reviewQueue.length}). ` +
+                    `${formatHunkPosition()} There are no previous items.`
                 }
 
-                return `Navigated to previous file. ${formatState(after)}`
+                reviewPosition--
+                await goToHunk(reviewQueue[reviewPosition])
+
+                return `Navigated to previous item. ${formatHunkPosition()}`
               }
 
               case "status": {
                 const state = await getState()
-                if (!state.open) return "Diff view is not currently open."
-                return `${formatState(state)}${formatFileList(state)}`
+                if (!state.open && reviewQueue.length === 0) {
+                  return "No review in progress and diff view is not open."
+                }
+
+                if (reviewQueue.length === 0) {
+                  return "Diff view is open but no review queue. Call 'start_review' to begin."
+                }
+
+                return formatHunkPosition()
               }
 
               case "close": {
                 await nvimExpr(`luaeval("require('diffview').close()")`)
-                return "Closed the diff view in Neovim."
+
+                // Clear review state
+                const itemCount = reviewQueue.length
+                reviewQueue = []
+                reviewPosition = -1
+                reviewRef = undefined
+                reviewFiles = undefined
+
+                return `Closed the diff view and ended the review` +
+                  (itemCount > 0 ? ` (reviewed ${itemCount} item${itemCount === 1 ? "" : "s"}).` : ".")
               }
             }
           } catch (e: any) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-nvim-diff-review",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agent-driven guided code review for Neovim + OpenCode",
   "main": "opencode-plugin/index.ts",
   "keywords": [