feat: add code reference picker for navigating file references in AI responses (#151)

* feat: adds code reference picker to navigate file:line references in LLM responses

* feat(config): add system prompt for file URI navigation
- introduce a new configurable system prompt to customize assistant behavior
- include guidance for file referencing to assist users with integration
- modifies message sending logic to incorporate the system prompt if set
- changes to reference detection streamline navigation for file-related responses

* fix(reference_picker): clean up display formatting

- Remove dead code referencing non-existent ref.context field
- Only show line number in display when present (avoid 'path:?')

* feat(references): parse references on message completion and display icons

- Parse file references when session becomes idle (AI done responding)
- Cache parsed references per-message for faster picker opening
- Handle session load from previous sessions
- Display reference icon before recognized file paths in output
- Subscribe to 'messages' state changes to parse loaded sessions
- Update test expected data files with new icon rendering

* refactor(references): simplify to only support file:// URIs

Remove legacy path:line and path-only pattern detection in favor of
exclusively parsing file:// URIs. This simplifies the code significantly
and avoids false positives from ambiguous path patterns.

The system prompt instructs the LLM to use file:// URIs, making the
legacy patterns unnecessary.

* docs(config): clarify system prompt behavior in config.lua
- refine explanation for system prompt usage in assistant responses
- emphasize file URI scheme for better navigation and tooling integration

* feat(config): update system prompt for file referencing in responses
- remove old system prompt setting in configuration
- replace it with a hardcoded prompt including URI format examples
- modifies behavior to improve navigation and tooling integration

* feat(ui): enhance file URI parsing to support line ranges
- add support for line range format: file://path:start-end
- modify regex pattern to accommodate optional end line numbers
- update reference structure to include optional end_pos for highlighting

* fix(core): update guidance for file reference formatting
- enhance clarity in the instructions for referencing files
- emphasize the use of the file:// URI scheme as critical
- provide examples to illustrate correct and incorrect formats
- ensure compatibility with the existing reference picker for navigation

* fix(ui): enhance reference formatting in picker
- improve reference location display by including line and column info
- handle cases where end position is available for better accuracy
- simplify display logic to ensure consistent output for references

* feat(ui): add preview support to telescope picker

- populate entry path, lnum, and col in telescope entries to support previewers
- enable file previewer configuration when options request file preview
- ensures code references can be previewed directly in the telescope picker UI

* fix(core): mandate backticks for file references in system prompt
- update system prompt to explicitly require backticks around file:// URIs
- add examples distinguishing correct backticked format from incorrect ones
- ensures file references are consistently formatted for UI and parsing

* feat(readme): update key bindings and add functionality details
- add key binding for timeline picker with `<leader>oT`
- include new key binding for browsing code references with `gr`
- clarify command usage for creating and selecting sessions
- touches(config): update default keyboard shortcuts for new features

* test: regenerate expected snapshots after upstream merge

Icon characters changed in upstream, requiring test snapshot updates

* feat(ui): fix icon merge

* test: update snapshots after icon fix

* feat: add telescope support for code range highlighting

Telescope supports highlighting line ranges in the file previewer using
the lnend field. Map end_pos[1] to lnend so that references with line
ranges (file://path:start-end) get highlighted in Telescope previewer.

* fix: use vim_buffer_vimgrep previewer for range highlighting

The default file_previewer uses the 'cat' previewer which doesn't call
jump_to_line, so lnend field is ignored. Switch to vim_buffer_vimgrep
which properly highlights line ranges using the lnend field.

* chore: trigger CI rerun

* feat: add fzf-lua file preview and line navigation support

Add builtin previewer support to fzf-lua picker backend with automatic
line/column positioning for code references.

Changes:
- Enable 'builtin' previewer when preview='file'
- Append file:line:col: format to entries for fzf-lua parsing
- Update fn_fzf_index to strip position info before matching
- Supports navigation to specific lines (range highlighting shows start line only)

Implementation details:
- Uses tab separator between display text and file position
- fzf-lua's entry_to_file() automatically parses path:line:col: format
- Cursorline highlights the target line in preview
- Gracefully degrades when preview is disabled

Comparison with other pickers:
- Telescope: Full range highlighting (start-end lines)
- Snacks: Full range highlighting (start-end lines)
- fzf-lua: Single line highlighting (cursorline at start)
- Mini.pick: No file preview support

* fix: use nbsp separator for fzf-lua entries (not tab)

fzf-lua uses nbsp (U+2002 EN SPACE) as the standard separator between
display text and file path info, not tab. The builtin previewer parses
entries by splitting on utils.nbsp and extracting the path:line:col:
portion.

From fzf-lua/path.lua entry_to_file():
  local parts = utils.strsplit(entry, utils.nbsp)
  for i = 1, #parts - 1 do
    if s:match(".-:%d+:") then break end
    idx0 = idx0 + #s + #utils.nbsp
  end
  return entry:sub(idx0), idx0

Changes:
- Use nbsp (\xe2\x80\x82) instead of \t as separator
- Update fn_fzf_index to split by nbsp
- Use file_path (relative) before file (absolute) for correct resolution

This fixes 'Unable to stat file' errors in preview.

Author: aweis89

README.md

@@ -353,7 +353,8 @@ The plugin provides the following actions that can be triggered via keymaps, com
 | Close UI windows                                          | `<leader>oq`                          | `:Opencode close`                           | `require('opencode.api').close()`                                      |
 | Select and load session                                   | `<leader>os`                          | `:Opencode session select`                  | `require('opencode.api').select_session()`                             |
 | **Select and load child session**                         | `<leader>oS`                          | `:Opencode session select_child`            | `require('opencode.api').select_child_session()`                       |
-| Open timeline picker (navigate/undo/redo/fork to message) | -                                     | `:Opencode timeline`                        | `require('opencode.api').timeline()`                                   |
+| Open timeline picker (navigate/undo/redo/fork to message) | `<leader>oT`                          | `:Opencode timeline`                        | `require('opencode.api').timeline()`                                   |
+| Browse code references from conversation                  | `gr` (window)                         | `:Opencode references` / `/references`      | `require('opencode.api').references()`                                 |
 | Configure provider and model                              | `<leader>op`                          | `:Opencode configure provider`              | `require('opencode.api').configure_provider()`                         |
 | Open diff view of changes                                 | `<leader>od`                          | `:Opencode diff open`                       | `require('opencode.api').diff_open()`                                  |
 | Navigate to next file diff                                | `<leader>o]`                          | `:Opencode diff next`                       | `require('opencode.api').diff_next()`                                  |

lua/opencode/api.lua

@@ -307,6 +307,10 @@ function M.focus_input()
   ui.focus_input({ restore_position = true, start_insert = true })
 end
 
+function M.references()
+  require('opencode.ui.reference_picker').pick()
+end
+
 function M.debug_output()
   if not config.debug.enabled then
     vim.notify('Debugging is not enabled in the config', vim.log.levels.WARN)
@@ -1228,6 +1232,10 @@ M.commands = {
     desc = 'Paste image from clipboard and add to context',
     fn = M.paste_image,
   },
+  references = {
+    desc = 'Browse code references from conversation',
+    fn = M.references,
+  },
 }
 
 M.slash_commands_map = {
@@ -1245,6 +1253,7 @@ M.slash_commands_map = {
   ['/sessions'] = { fn = M.select_session, desc = 'Select session' },
   ['/share'] = { fn = M.share, desc = 'Share current session' },
   ['/timeline'] = { fn = M.timeline, desc = 'Open timeline picker' },
+  ['/references'] = { fn = M.references, desc = 'Browse code references from conversation' },
   ['/undo'] = { fn = M.undo, desc = 'Undo last action' },
   ['/unshare'] = { fn = M.unshare, desc = 'Unshare current session' },
   ['/rename'] = { fn = M.rename_session, desc = 'Rename current session' },

lua/opencode/config.lua

@@ -51,6 +51,7 @@ M.defaults = {
       ['[['] = { 'prev_message' },
       ['<tab>'] = { 'toggle_pane', mode = { 'n', 'i' } },
       ['i'] = { 'focus_input' },
+      ['gr'] = { 'references', desc = 'Browse code references' },
       ['<leader>oS'] = { 'select_child_session' },
       ['<leader>oD'] = { 'debug_message' },
       ['<leader>oO'] = { 'debug_output' },
@@ -69,6 +70,7 @@ M.defaults = {
       ['<up>'] = { 'prev_prompt_history', mode = { 'n', 'i' } },
       ['<down>'] = { 'next_prompt_history', mode = { 'n', 'i' } },
       ['<M-m>'] = { 'switch_mode', mode = { 'n', 'i' } },
+      ['gr'] = { 'references', desc = 'Browse code references' },
       ['<leader>oS'] = { 'select_child_session' },
       ['<leader>oD'] = { 'debug_message' },
       ['<leader>oO'] = { 'debug_output' },

lua/opencode/core.lua

@@ -167,6 +167,21 @@ M.send_message = Promise.async(function(prompt, opts)
     state.current_mode = opts.agent
   end
 
+  params.system = [[
+# Code References
+
+**CRITICAL: Always use the file:// URI scheme when referencing files in responses AND wrap them in backticks.**
+
+Format: `file://path/to/file.lua`, `file://path/to/file.lua:42`, or `file://path/to/file.lua:42-50`
+
+Examples:
+- CORRECT: "The error is in `file://src/services/process.ts:712`"
+- INCORRECT: "The error is in file://src/services/process.ts:712"
+- INCORRECT: "The error is in src/services/process.ts:712"
+
+This matches the file:// URI format that the reference picker already parses from your responses, enabling automatic navigation.
+]]
+
   params.parts = context.format_message(prompt, opts.context)
   M.before_run(opts)
 

lua/opencode/init.lua

@@ -16,6 +16,7 @@ function M.setup(opts)
   require('opencode.event_manager').setup()
   require('opencode.context').setup()
   require('opencode.ui.context_bar').setup()
+  require('opencode.ui.reference_picker').setup()
 end
 
 return M

lua/opencode/types.lua

@@ -289,6 +289,7 @@
 ---@class OpencodeMessage
 ---@field info MessageInfo Metadata about the message
 ---@field parts OpencodeMessagePart[] Parts that make up the message
+---@field references CodeReference[]|nil Parsed file references from text parts (cached)
 
 ---@class MessageInfo
 ---@field id string Unique message identifier
@@ -488,3 +489,13 @@
 ---@field messages number Number of messages reverted
 ---@field tool_calls number Number of tool calls reverted
 ---@field files table<string, {additions: number, deletions: number}> Summary of file changes reverted
+
+---@class CodeReference
+---@field file_path string Relative or absolute file path
+---@field line number|nil Line number (1-indexed)
+---@field column number|nil Column number (optional)
+---@field message_id string ID of the message containing this reference
+---@field match_start number Start position of match in original text
+---@field match_end number End position of match in original text
+---@field file string Absolute file path (for Snacks picker preview)
+---@field pos number[]|nil Position as {line, col} for Snacks picker preview

lua/opencode/ui/base_picker.lua

@@ -17,6 +17,7 @@ local Promise = require('opencode.promise')
 ---@field title string|fun(): string The picker title
 ---@field width? number Optional width for the picker (defaults to config or current window width)
 ---@field multi_selection? table<string, boolean> Actions that support multi-selection
+---@field preview? "file"|"none"|false Preview mode: "file" for file preview, "none" or false to disable
 
 ---@class TelescopeEntry
 ---@field value any
@@ -89,14 +90,28 @@ local function telescope_ui(opts)
   ---@param item any
   ---@return TelescopeEntry
   local function make_entry(item)
-    return {
+    local entry = {
       value = item,
       display = function(entry)
         local formatted = opts.format_fn(entry.value):to_formatted_text()
         return displayer(formatted)
       end,
       ordinal = opts.format_fn(item):to_string(),
     }
+
+    if type(item) == 'table' then
+      entry.path = item.file or item.file_path or item.path or item.filename
+      entry.lnum = item.line or item.lnum
+      entry.col = item.column or item.col
+      -- Support line ranges for preview highlighting
+      if item.end_pos and type(item.end_pos) == 'table' and item.end_pos[1] then
+        entry.lnend = item.end_pos[1]
+      end
+    elseif type(item) == 'string' then
+      entry.path = item
+    end
+
+    return entry
   end
 
   local function refresh_picker()
@@ -111,6 +126,7 @@ local function telescope_ui(opts)
     prompt_title = opts.title,
     finder = finders.new_table({ results = opts.items, entry_maker = make_entry }),
     sorter = conf.generic_sorter({}),
+    previewer = opts.preview == 'file' and require('telescope.previewers').vim_buffer_vimgrep.new({}) or nil,
     layout_config = opts.width and {
         width = opts.width + 7, -- extra space for telescope UI
       } or nil,
@@ -193,9 +209,15 @@ local function fzf_ui(opts)
         ['--multi'] = has_multi_action and true or nil,
       },
       _headers = { 'actions' },
+      -- Enable builtin previewer for file preview support
+      previewer = opts.preview == 'file' and 'builtin' or nil,
       fn_fzf_index = function(line)
+        -- Strip the appended file:line:col info before matching
+        -- fzf-lua uses nbsp (U+2002 EN SPACE) as separator
+        local nbsp = '\xe2\x80\x82'
+        local display_part = line:match('^([^' .. nbsp .. ']+)') or line
         for i, item in ipairs(opts.items) do
-          if opts.format_fn(item):to_string() == line then
+          if opts.format_fn(item):to_string() == display_part then
             return i
           end
         end
@@ -207,7 +229,33 @@ local function fzf_ui(opts)
   local function create_finder()
     return function(fzf_cb)
       for _, item in ipairs(opts.items) do
-        fzf_cb(opts.format_fn(item):to_string())
+        local line_str = opts.format_fn(item):to_string()
+        
+        -- For file preview support, append file:line:col format
+        -- fzf-lua's builtin previewer automatically parses this format
+        if opts.preview == 'file' and type(item) == 'table' then
+          local file_path = item.file_path or item.path or item.filename or item.file
+          local line = item.line or item.lnum
+          local col = item.column or item.col
+          
+          if file_path then
+            -- fzf-lua parses "path:line:col:" format for preview positioning
+            local pos_info = file_path
+            if line then
+              pos_info = pos_info .. ':' .. tostring(line)
+              if col then
+                pos_info = pos_info .. ':' .. tostring(col)
+              end
+              pos_info = pos_info .. ':'
+            end
+            -- Append position info after nbsp separator (fzf-lua standard)
+            -- nbsp is U+2002 EN SPACE, not regular tab
+            local nbsp = '\xe2\x80\x82'
+            line_str = line_str .. nbsp .. pos_info
+          end
+        end
+        
+        fzf_cb(line_str)
       end
       fzf_cb()
     end
@@ -341,15 +389,23 @@ end
 local function snacks_picker_ui(opts)
   local Snacks = require('snacks')
 
+  -- Determine if preview is enabled
+  local has_preview = opts.preview == 'file'
+
+  -- Choose layout preset based on preview
+  local layout_preset = has_preview and 'default' or 'select'
+
   local snack_opts = {
     title = opts.title,
     layout = {
-      preset = 'select',
+      preset = layout_preset,
       config = function(layout)
         local width = opts.width and (opts.width + 3) or nil -- extra space for snacks UI
-        layout.layout.width = width
-        layout.layout.max_width = width
-        layout.layout.min_width = width
+        if not has_preview then
+          layout.layout.width = width
+          layout.layout.max_width = width
+          layout.layout.min_width = width
+        end
         return layout
       end,
     },
@@ -378,6 +434,11 @@ local function snacks_picker_ui(opts)
     },
   }
 
+  -- Add file preview if enabled
+  if has_preview then
+    snack_opts.preview = 'file'
+  end
+
   snack_opts.win = snack_opts.win or {}
   snack_opts.win.input = snack_opts.win.input or { keys = {} }
 

lua/opencode/ui/formatter.lua

@@ -466,8 +466,39 @@ end
 ---@param output Output Output object to write to
 ---@param text string
 function M._format_assistant_message(output, text)
-  -- output:add_empty_line()
-  output:add_lines(vim.split(text, '\n'))
+  local reference_picker = require('opencode.ui.reference_picker')
+  local references = reference_picker.parse_references(text, '')
+
+  -- If no references, just add the text as-is
+  if #references == 0 then
+    output:add_lines(vim.split(text, '\n'))
+    return
+  end
+
+  -- Sort references by match_start position (ascending)
+  table.sort(references, function(a, b)
+    return a.match_start < b.match_start
+  end)
+
+  -- Build a new text with icons inserted before each reference
+  local result = ''
+  local last_pos = 1
+  local ref_icon = icons.get('reference')
+
+  for _, ref in ipairs(references) do
+    -- Add text before this reference
+    result = result .. text:sub(last_pos, ref.match_start - 1)
+    -- Add the icon and the reference
+    result = result .. ref_icon .. text:sub(ref.match_start, ref.match_end)
+    last_pos = ref.match_end + 1
+  end
+
+  -- Add any remaining text after the last reference
+  if last_pos <= #text then
+    result = result .. text:sub(last_pos)
+  end
+
+  output:add_lines(vim.split(result, '\n'))
 end
 
 ---@param output Output Output object to write to

lua/opencode/ui/highlight.lua

@@ -34,6 +34,7 @@ function M.setup()
     vim.api.nvim_set_hl(0, 'OpencodeContextSwitchOn', { link = '@label', default = true })
     vim.api.nvim_set_hl(0, 'OpencodePickerTime', { link = 'Comment', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeDebugText', { link = 'Comment', default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeReference', { fg = '#1976D2', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeReasoningText', { link = 'Comment', default = true })
   else
     vim.api.nvim_set_hl(0, 'OpencodeBorder', { fg = '#616161', default = true })
@@ -65,6 +66,7 @@ function M.setup()
     vim.api.nvim_set_hl(0, 'OpencodeContextSwitchOn', { link = '@label', default = true })
     vim.api.nvim_set_hl(0, 'OpencodePickerTime', { link = 'Comment', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeDebugText', { link = 'Comment', default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeReference', { fg = '#7AA2F7', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeReasoningText', { link = 'Comment', default = true })
   end
 end

lua/opencode/ui/icons.lua

@@ -25,6 +25,7 @@ local presets = {
     folder = ' ',
     attached_file = '󰌷 ',
     agent = '󰚩 ',
+    reference = ' ',
     reasoning = '󰧑 ',
     -- statuses
     status_on = ' ',
@@ -61,6 +62,7 @@ local presets = {
     folder = '[@]',
     attached_file = '@',
     agent = '@',
+    reference = '@',
     -- statuses
     status_on = 'ON',
     status_off = 'OFF',