opencode-nvim-diff-review 0.2.0 → 0.4.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
 
@@ -140,13 +146,33 @@ 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
@@ -154,29 +180,26 @@ Key design decisions:
 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
-
-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.
+### Expand (surrounding context)
 
-### 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 = {}
 
@@ -16,6 +23,13 @@ local M = {}
 --- Used by the cleanup hooks to avoid removing buffers the user had open.
 local pre_diffview_bufs = {}
 
+--- Pending cursor position to set after diffview finishes opening a file.
+--- DiffviewGoTo stores the target here, and the autocmd on DiffviewDiffBufWinEnter
+--- applies it. This avoids a race with diffview's async file loading which resets
+--- the cursor to line 1 after opening.
+--- @type { file: string, line: number }?
+local pending_goto = nil
+
 --- Query the current diffview state.
 --- Returns a JSON string with:
 ---   open: boolean          - whether diffview is active
@@ -68,6 +82,182 @@ 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
+    local err_msg = table.concat(diff_lines, "\n")
+    return vim.json.encode({
+      error = "git diff failed: " .. (err_msg ~= "" and err_msg or "unknown error"),
+    })
+  end
+
+  if #diff_lines == 0 then
+    return vim.json.encode({})
+  end
+
+  -- Normalize hunk headers for -U0 output.
+  -- With -U0, git omits the count when it's 1 (e.g., "@@ -134 +134,4 @@"
+  -- instead of "@@ -134,1 +134,4 @@"). diffview's parser expects the
+  -- comma-separated form, so we normalize before parsing.
+  for i, line in ipairs(diff_lines) do
+    local old_spec, new_spec = line:match("^@@ %-(%S+) %+(%S+) @@")
+    if old_spec then
+      -- Ensure both sides have the ",count" format
+      if not old_spec:match(",") then
+        old_spec = old_spec .. ",1"
+      end
+      if not new_spec:match(",") then
+        new_spec = new_spec .. ",1"
+      end
+      diff_lines[i] = "@@ -" .. old_spec .. " +" .. new_spec .. " @@"
+    end
+  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 hunk.
+---
+--- Finds the file in diffview's file list, switches to it if needed,
+--- positions the cursor at the hunk, and folds all other regions so only
+--- the target hunk (with a few context lines) is visible.
+---
+--- @param file string Repo-relative file path
+--- @param line_or_hunk number|table Either a line number or a hunk spec table:
+---                                   { new_start, new_count, old_start, old_count }
+--- @return string JSON-encoded result: { ok: true } or { error: string }
+function DiffviewGoTo(file, line_or_hunk)
+  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
+
+  -- Store the target so the autocmd can position the cursor and set up folds
+  -- after diffview finishes its async file loading.
+  local hunk_spec = type(line_or_hunk) == "table" and line_or_hunk or nil
+  local target_line = hunk_spec
+    and (hunk_spec.new_start > 0 and hunk_spec.new_start or 1)
+    or (type(line_or_hunk) == "number" and line_or_hunk or 1)
+
+  pending_goto = {
+    file = file,
+    line = target_line,
+    hunk = hunk_spec,
+  }
+
+  -- 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)
+  else
+    -- Already on the right file — apply directly
+    M._apply_pending_goto()
+  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)
@@ -79,6 +269,130 @@ function M.on_view_opened(view)
   end
 end
 
+--- Number of context lines to show above and below a focused hunk.
+local HUNK_CONTEXT = 3
+
+--- Apply a pending cursor position and hunk focus after diffview has finished
+--- loading a file. Called from the DiffviewDiffBufWinEnter autocmd and from
+--- DiffviewGoTo when the file is already displayed.
+function M._apply_pending_goto()
+  if not pending_goto then return end
+
+  local target_line = pending_goto.line
+  local hunk = pending_goto.hunk
+  pending_goto = nil
+
+  -- Small delay to ensure diffview's own cursor positioning (which resets to
+  -- line 1 on file_open_new) has completed before we override it.
+  vim.defer_fn(function()
+    local ok, lib = pcall(require, "diffview.lib")
+    if not ok then return end
+
+    local view = lib.get_current_view()
+    if not view then return end
+
+    local layout = view.cur_layout
+    if not layout then return end
+
+    -- Get the main window (right-hand / "b" side in a 2-way diff)
+    local main_win = layout:get_main_win()
+    if not main_win or not main_win.id or not vim.api.nvim_win_is_valid(main_win.id) then
+      return
+    end
+
+    local main_file = main_win.file
+    if not main_file or not main_file.bufnr or not vim.api.nvim_buf_is_loaded(main_file.bufnr) then
+      return
+    end
+
+    -- Position cursor at the hunk
+    local max_line = vim.api.nvim_buf_line_count(main_file.bufnr)
+    local line = math.min(math.max(target_line or 1, 1), max_line)
+    vim.api.nvim_win_set_cursor(main_win.id, { line, 0 })
+    vim.api.nvim_set_current_win(main_win.id)
+
+    -- Set up hunk-focus folds if we have hunk boundaries
+    if hunk then
+      M._apply_hunk_focus(view, hunk)
+    end
+
+    vim.cmd("normal! zz")
+  end, 50)
+end
+
+--- Create folds that hide everything except the target hunk and a few
+--- context lines around it. Switches both diff windows to foldmethod=manual.
+---
+--- @param view table The current DiffView
+--- @param hunk table Hunk spec: { new_start, new_count, old_start, old_count }
+function M._apply_hunk_focus(view, hunk)
+  local layout = view.cur_layout
+  if not layout then return end
+
+  -- Compute the visible range for each side (old = "a", new = "b").
+  -- layout.a and layout.b are Window objects with .id and .file properties.
+  -- A hunk with count=0 means pure insertion/deletion — show context around
+  -- the start line instead.
+  local sides = {}
+
+  -- "b" side (new/right) — uses new_start/new_count
+  if layout.b and layout.b.file and layout.b.file.bufnr
+    and vim.api.nvim_buf_is_loaded(layout.b.file.bufnr)
+  then
+    local lcount = vim.api.nvim_buf_line_count(layout.b.file.bufnr)
+    local hunk_first = hunk.new_start > 0 and hunk.new_start or 1
+    local hunk_last = hunk.new_count > 0 and (hunk.new_start + hunk.new_count - 1) or hunk_first
+    table.insert(sides, {
+      win_id = layout.b.id,
+      lcount = lcount,
+      hunk_first = hunk_first,
+      hunk_last = hunk_last,
+    })
+  end
+
+  -- "a" side (old/left) — uses old_start/old_count
+  if layout.a and layout.a.file and layout.a.file.bufnr
+    and vim.api.nvim_buf_is_loaded(layout.a.file.bufnr)
+  then
+    local lcount = vim.api.nvim_buf_line_count(layout.a.file.bufnr)
+    local hunk_first = hunk.old_start > 0 and hunk.old_start or 1
+    local hunk_last = hunk.old_count > 0 and (hunk.old_start + hunk.old_count - 1) or hunk_first
+    table.insert(sides, {
+      win_id = layout.a.id,
+      lcount = lcount,
+      hunk_first = hunk_first,
+      hunk_last = hunk_last,
+    })
+  end
+
+  for _, side in ipairs(sides) do
+    if vim.api.nvim_win_is_valid(side.win_id) then
+      vim.api.nvim_win_call(side.win_id, function()
+        -- Switch to manual folds so we have full control
+        vim.wo.foldmethod = "manual"
+        vim.wo.foldenable = true
+
+        -- Remove all existing folds
+        pcall(vim.cmd, "normal! zE")
+
+        -- Visible range: hunk lines + context
+        local vis_first = math.max(1, side.hunk_first - HUNK_CONTEXT)
+        local vis_last = math.min(side.lcount, side.hunk_last + HUNK_CONTEXT)
+
+        -- Create fold above the visible range
+        if vis_first > 1 then
+          vim.cmd(string.format("1,%dfold", vis_first - 1))
+        end
+
+        -- Create fold below the visible range
+        if vis_last < side.lcount then
+          vim.cmd(string.format("%d,%dfold", vis_last + 1, side.lcount))
+        end
+      end)
+    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
@@ -103,7 +417,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 +431,20 @@ 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
+
+  -- Listen for diffview's DiffviewDiffBufWinEnter autocmd to apply pending
+  -- cursor positions after async file loading completes.
+  vim.api.nvim_create_autocmd("User", {
+    pattern = "DiffviewDiffBufWinEnter",
+    callback = function()
+      M._apply_pending_goto()
+    end,
+  })
 
   -- 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,19 @@ 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.
  *
@@ -87,6 +103,65 @@ const discoverNvimSocket = async (): Promise<string | null> => {
   return fallback
 }
 
+// --- Helpers ---
+
+const STATUS_LABELS: Record<string, string> = {
+  M: "modified",
+  A: "added",
+  D: "deleted",
+  R: "renamed",
+  C: "copied",
+  T: "type-changed",
+}
+
+const statusLabel = (status: string | undefined): string =>
+  (status && STATUS_LABELS[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.
+ * A hunk is uniquely identified by {file, old_start, old_count, new_start, new_count}.
+ */
+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
+  )
+
+/**
+ * Format a summary of the files covered in the review queue.
+ */
+const formatQueueSummary = (queue: HunkItem[]): string => {
+  const fileGroups = new Map<string, { status: string; count: number }>()
+  for (const item of queue) {
+    const existing = fileGroups.get(item.file)
+    if (existing) {
+      existing.count++
+    } else {
+      fileGroups.set(item.file, { status: item.status, count: 1 })
+    }
+  }
+  const lines = Array.from(fileGroups.entries()).map(
+    ([file, { status, count }]) =>
+      `  ${file} (${statusLabel(status)}) — ${count} hunk${count === 1 ? "" : "s"}`
+  )
+  return `\nFiles in review:\n${lines.join("\n")}`
+}
+
+// --- Plugin ---
+
 export const DiffReviewPlugin: Plugin = async (ctx) => {
   return {
     tool: {
@@ -100,53 +175,77 @@ 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) {
@@ -174,117 +273,174 @@ 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, '\\"')
+            // Pass hunk boundaries so Lua can set up folds to focus on this hunk
+            const hunkSpec = `{new_start=${item.new_start},new_count=${item.new_count},old_start=${item.old_start},old_count=${item.old_count}}`
+            const raw = await nvimExpr(
+              `luaeval("DiffviewGoTo('${file}', ${hunkSpec})")`
+            )
+            const result = JSON.parse(raw.trim())
+            if (result.error) throw new Error(result.error)
+            // Give diffview time to switch files and the Lua side to
+            // position cursor and set up folds
+            await Bun.sleep(500)
           }
 
           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()}` +
+                  formatQueueSummary(reviewQueue)
               }
 
               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.2.0",
+  "version": "0.4.0",
   "description": "Agent-driven guided code review for Neovim + OpenCode",
   "main": "opencode-plugin/index.ts",
   "keywords": [